>From e8173c4a555c0c64a71670790510c530d37b8657 Mon Sep 17 00:00:00 2001 From: Tony Ibbs Date: Thu, 27 Jan 2011 10:34:50 +0000 Subject: [PATCH] KBUS messaging subsystem Initial contribution / RFC. (This is a squashed merge up to 5dceafdd0381a9416e2c106d2bb9b35498d2be1f) Signed-off-by: Tony Ibbs --- Documentation/Kbus.txt | 1189 ++++++++++ include/linux/kbus_defns.h | 666 ++++++ init/Kconfig | 3 + ipc/Kconfig | 99 + ipc/Makefile | 1 + ipc/kbus.c | 5120 ++++++++++++++++++++++++++++++++++++++++++++ ipc/kbus_internal.h | 773 +++++++ 7 files changed, 7851 insertions(+), 0 deletions(-) create mode 100644 Documentation/Kbus.txt create mode 100644 include/linux/kbus_defns.h create mode 100644 ipc/Kconfig create mode 100644 ipc/kbus.c create mode 100644 ipc/kbus_internal.h diff --git a/Documentation/Kbus.txt b/Documentation/Kbus.txt new file mode 100644 index 0000000..e4d6e2f --- /dev/null +++ b/Documentation/Kbus.txt @@ -0,0 +1,1189 @@ +============================================= +KBUS -- Lightweight kernel-mediated messaging +============================================= + +Intention +========= +KBUS provides lightweight kernel-mediated messaging for Linux. + +* "lightweight" means that there is no intent to provide complex or + sophisticated mechanisms - if you need something more, consider DBUS or + other alternatives. + +* "kernel-mediated" means that the actual business of message passing and + message synchronisation is handled by a kernel module. + +* "for Linux" means what it says - the initial code is for the Linux kernel. + +Initial use is expected to be in embedded systems. + +There is (at least initially) no intent to aim for a "fast" system - this is +not aimed at real-time systems. + +Although the initial implementation is kernel-mediated, there is a mechanism +("Limpets") for commnicating KBUS messages between machnes. + +The basics +========== +Python and C +------------ +Although the KBUS kernel module is written in C, the module tests are written +in Python, and there is a Python module providing useful interfaces, which is +expected to be the normal way of using KBUS from Python. + +There is also a C library (libkbus) which provides a similar level of +abstraction, so that C programmers can use KBUS without having to handle the +low level details of sockets and message datastructures. Note that the C +programer using KBUS does need to have some awareness of how KBUS messages +work in order to get memory management right. + +Messages +======== +Message names +------------- +All messages have names - for instance "$.Sensors.Kitchen". + +All message names start with "$.", followed by one or more alphanumeric words +separated by dots. There are two wildcard characters, "*" and "%", which can +be the last word of a name. + +Thus (in some notation or other):: + + name := '$.' [ word '.' ]+ ( word | '*' | '%' ) + word := alphanumerics + +Case is significant. There is probably a limit on the maximum size of a +subname, and also on the maximum length of a message name. + +Names form a name hierarchy or tree - so "$.Sensors" might have children +"$.Sensors.Kitchen" and "$.Sensors.Bedroom". + +If the last word of a name is "*", then this is a wildcard name that also +includes all the child names at that level and below -- i.e., all the names +that start with the name up to the "*". So "$.Sensors.*" includes +"$.Sensors.Kitchen", "$.Sensors.Bedroom", "$.Sensors.Kitchen.FireAlarm", +"$.Sensors.Kitchen.Toaster", "$.Sensors.Bedroom.FireAlarm", and so on. + +If the last word of a name is "%", then this is a wildcard name that also +includes all the child names at that level -- i.e., all the names obtained by +replacing the "%" by another word. So "$.Sensors.%" includes +"$.Sensors.Kitchen" and "$.Sensors.Bedroom", but not +"$.Sensors.Kitchen.Toaster". + +Message ids +----------- +Every message is expected to have a unique id. + +A message id is made up of two parts, a network id and a serial number. + +The network id is used to carry useful information when a message is +transferred from one KBUS system to another (for instance, over a bridge). By +default (for local messages) it is 0. + +A serial number is used to identify the particular message within a network. + +If a message is sent via KBUS with a network id of 0, then KBUS itself will +assign a new message id to the message, with the network id (still) 0, and +with the serial number one more than the last serial number assigned. Thus for +local messages, message ids ascend, and their order is deterministic. + +If a message is sent via KBUS with a non-zero network id, then KBUS does not +touch its message id. + +Network ids are represented textually as ``{n,s}``, where ``n`` is the +network id and ``s`` is the serial number. + + Message id {0,0} is reserved for use as an invalid message id. Both + network id and serial number are unsigned 32-bit integers. Note that this + means that local serial numbers will eventually wrap. + +Message content +--------------- +Messages are made of the following parts: + +:start and end guards: + + These are unsigned 32-bit words. 'start_guard' is notionally "Kbus", + and 'end_guard' (the 32 bit word after the rest of the message) is + notionally "subK". Obviously that depends on how one looks at the 32-bit + word. Every message shall start with a start guard and end with an end + guard (but see `Message implementation`_ for details). + + These provide some help in checking that a message is well formed, and in + particular the end guard helps to check for broken length fields. + + If the message layout changes in an incompatible manner (this has happened + once, and is strongly discouraged), then the start and end guards change. + +Unset +~~~~~ +Unset values are 0, or have zero length (as appropriate). + +It is not possible for a message name to be unset. + +The message header +~~~~~~~~~~~~~~~~~~ +:message id: identifies this particular message. This is made up of a network + id and a serial number, and is discussed in `Message ids`_. + + When replying to a message, copy this value into the 'In reply to' field. + +:in_reply_to: is the message id of the message that this is a reply to. + + This shall be set to 0 unless this message *is* a reply to a previous + message. In other words, if this value is non-0, then the message *is* a + reply. + +:to: is the Ksock id identifying who the message is to be sent to. + + When writing a new message, this should normally be set to 0, meaning + "anyone listening" (but see below if "state" is being maintained). + + When replying to a message, it shall be set to the 'from' value of the + orginal message. + + When constructing a request message (a message wanting a reply), then it can + be set to a specific replier's Ksock id. When such a message is sent, if the + replier bound (at that time) does not have that specific Ksock id, then the + send will fail. + +:from: indicates the Ksock id of the message's sender. + + When writing a new message, set this to 0, since KBUS will set it. + + When reading a message, this will have been set by KBUS. + +:orig_from: this indicates the original sender of a message, when being + transported via Limpet. This will be documented in more detail in the future. + +:final_to: this indicates the final target of a message, when being + transported via Limpet. This will be documented in more detail in the future. + +:extra: this is a zero field, for future expansion. KBUS will always set this + field to zero. + +:flags: indicates extra information about the message. See `Message Flags`_ + for detailed information. + + When writing a message, typical uses include: + + * the message is URGENT + * a reply is wanted + + When reading a message, typical uses include: + + * the message is URGENT + * a reply is wanted + * a reply is wanted from the specific reader + + The top 16 bits of the flags field is reserved for use by the user - KBUS + will not touch it. + +:name_length: is the length of the message name in bytes. This will always be + non-zero, as a message name must always be given. + +:data_length: is the length of the message data in bytes. It may be zero + if there is no data associated with this message. + +:name: identifies the message. It must be terminated with a + zero byte (as is normal for C - in the Python binding a normal Python string + can be used, and the this will be done for you). Byte ordering is according + to that of the platform. + + In an "entire" message (see `Message implementation`_ below) the name shall + be padded out to a multiple of 4 bytes. Neither the terminating zero byte + nor the padding are included in the name length. Padding should be with + zero bytes. + +:data: is optional. KBUS does not touch the content of the + data, but just copies it. Byte ordering is according to that of the + platform. + + In an "entire" message (see `Message implementation`_ below) the data shall, + if present, be padded out to a multiple of 4 bytes. This padding is not + included in the data length, and the padding bytes may be whatever byte + values are convenient to the user. KBUS does not guarantee to copy the exact + given padding bytes (in fact, current implementations just ignore them). + +Message implementation +~~~~~~~~~~~~~~~~~~~~~~ +There are two ways in which a message may be constructed, "pointy" and +"entire". +See the ``kbus_defns.h`` header file for details. + +.. note:: The Python binding hides most of the detail of the message + implementation from the user, so if you are using Python you may be able to + skip this section. + +In a "pointy" message, the ``name`` and ``data`` fields in the message header +are C pointers to the actual name and data. If there is no data, then the +``data`` field is NULL. This is probably the simplest form of message for a C +programmer to create. This might be represented as:: + + start_guard: 'Kbus' + id: (0,0) + in_reply_to: (0,0) + to: 0 + from: 0 + name_len: 6 + data_len: 0 + name: ---------------------------> "$.Fred" + data: NULL + end_guard: 'subK' + +or (with data):: + + start_guard: 'Kbus' + id: (0,0) + in_reply_to: (0,0) + to: 0 + from: 0 + name_len: 6 + data_len: 7 + name: ---------------------------> "$.Fred" + data: ---------------------------> "abc1234" + end_guard: 'subK' + +.. warning:: When writing a "pointy" message in C, be very careful not to + free the name and data between the ``write`` and the SEND, as it is + only when the message is sent that KBUS actually follows the ``name`` and + ``data`` pointers. + + *After* the SEND, KBUS will have taken its own copies of the name and + (any) data. + +In an "entire" message, both ``name`` and ``data`` fields are required to be +NULL. The message header is followed by the message name (padded as described +above), any message data (also padded), and another end guard. This might be +represented as:: + + start_guard: 'Kbus' + id: (0,0) + in_reply_to: (0,0) + to: 0 + from: 0 + name_len: 6 + data_len: 0 + name: NULL + data: NULL + end_guard: 'subK' + name_data: '$.Fred\x0\x0' + end_guard: 'subK' + +or (again with data):: + + start_guard: 'Kbus' + id: (0,0) + in_reply_to: (0,0) + to: 0 + from: 0 + name_len: 6 + data_len: 7 + name: NULL + data: NULL + end_guard: 'subK' + name_data: '$.Fred\x0\x0' + data_data: 'abc1234\x0' + end_guard: 'subK' + +Note that in these examples: + +1. The message name is padded out to 6 bytes of name, plus one of terminating + zero byte, plus another zero byte to make 8, but the message's ``name_len`` + is still 6. +2. When there is no data, there is no "data data" after the name data. +3. When there is data, the data is presented after the name, and is padded out + to a multiple of 4 bytes (but without the necessity for a terminating zero + byte, so it is possible to have no pad bytes if the data length is already + a multiple of 4). Again, the ``data_len`` always reflects the "real" data + length. +4. Although the data shown is presented as ASCII strings for these examples, + it really is just bytes, with no assumption of its content/meaning. + +When writing/sending messages, either form may be used (again, the "pointy" +form may be simpler for C programmers). + +When reading messages, however, the "entire" form is always returned - this +removes questions about needing to free multiple returned datastructures (for +instance, what to do if the user were to ask for the NEXTMSG, read a few +bytes, and then DISCARD the rest). + +Limits +~~~~~~ +Message names may not be shorter than 3 characters (since they must be at +least "$." plus another character). An arbitrary limit is also placed on the +maximum message length - this is currently 1000 characters, but may be +reviewed in the future. + +Message data may, of course, be of zero length. + +When reading a message, an "entire" message is always returned. + + .. note:: When using C to work with KBUS messages, it is generally + ill-advised to reference the message name and data "directly":: + + char *name = msg->name; + uint8_t *data = msg->data; + + since this will work for "pointy" messages, but not for "entire" + messages (where the ``name`` field will be NULL). Instead, it + is always better to do:: + + char *name = kbus_msg_name_ptr(msg); + uint8_t *data = kbus_msg_data_ptr(msg); + + regardless of the message type. + +Message flags +------------- +KBUS reserves the bottom 16 bits of the flags word for predefined purposes +(although not all of those bits are yet used), and guarantees not to touch the +top 16 bits, which are available for use by the programmer as a particular +application may wish. + +The WANT_A_REPLY bit is set by the sender to indicate that a +reply is wanted. This makes the message into a request. + + Note that setting the WANT_A_REPLY bit (i.e., a request) and + setting 'in_reply_to' (i.e., a reply) is bound to lead to + confusion, and the results are undefined (i.e., don't do it). + +The WANT_YOU_TO_REPLY bit is set by KBUS on a particular message +to indicate that the particular recipient is responsible for replying +to (this instance of the) message. Otherwise, KBUS clears it. + +The SYNTHETIC bit is set by KBUS when it generates a Status message, for +instance when a replier has gone away and will therefore not be sending a +reply to a request that has already been queued. + + Note that KBUS does not check that a sender has not set this + flag on a message, but doing so may lead to confusion. + +The URGENT bit is set by the sender if this message is to be +treated as urgent - i.e., it should be added to the *front* of the +recipient's message queue, not the back. + +Send flags +~~~~~~~~~~ +There are two "send" flags, ALL_OR_WAIT and ALL_OR_FAIL. +Either one may be set, or both may be unset. + + If both are set, the message will be rejected as invalid. + + Both flags are ignored in reply messages (i.e., messages with the + 'in_reply_to' field set). + +If a message has ALL_OR_FAIL set, then a SEND will only succeed if the message +could be added to all the (intended) recipient's message queues. Otherwise, +SEND returns -EBUSY. + +If a message has ALL_OR_WAIT set, then a SEND will only succeed if the message +could be added to all the (intended) recipient's message queues. Otherwise +SEND returns -EAGAIN. In this case, the message is still being sent, and the +caller should either call DISCARD (to drop it), or else use poll/select to +wait for the send to finish. It will not be possible to call "write" until the +send has completed or been discarded. + +These are primarily intended for use in debugging systems. In particular, note +that the mechanisms dealing with ALL_OR_WAIT internally are unlikely to be +very efficient. + +.. note:: The send flags will be less effective when messages are being + mediated via Limpets, as remote systems are involved. + +Things KBUS changes in a message +-------------------------------- +In general, KBUS leaves the content of a message alone - mostly so that an +individual KBUS module can "pass through" messages from another domain. +However, it does change: + +- the message id's serial number (but only if its network id is unset) +- the 'from' id (to indicate the Ksock this message was sent from) +- the WANT_YOU_TO_REPLY bit in the flags (set or cleared as appropriate) +- the SYNTHETIC bit, which will always be unset in a message sent by a + Sender + +KBUS will always set the 'extra' field to zero. + +Limpets will change: + +- the network id in any field that has one. +- the 'orig_from' and 'final_to' fields (which in general should only be + manipulated by Limpets). + +Types of message +================ +There are four basic message types: + +* Announcement -- a message aimed at any listeners, expecting no reply +* Request -- a message aimed at a replier, who is expected to reply +* Reply -- a reply to a request +* Status -- a message generated by KBUS + +The Python interface provides a Message base class, and subclasses thereof for +each of the "user" message types (but not currently for Status). + +Announcements +------------- +An announcement is the "plain" message type. It is a message that is being +sent for all bound listeners to "hear". + +When creating a new announcement message, it has: + + :message id: see `Message ids`_ + :in reply to: unset (it's not a reply) + :to: unset (all announcements are broadcast to any listeners) + :from: unset (KBUS will set it) + :flags: typically unset, see `Message flags`_ + :message name: as appropriate + :message data: as appropriate + +The Python interface provides an ``Announcement`` class to help in creating an +announcement message. + +Request message +--------------- +A request message is a message that wants a reply. + +Since only one Ksock may bind as a replier for a given message name, a +request message wants a reply from a single Ksock. By default, this is +whichever Ksock has bound to the message name at the moment of sending, but +see `Stateful transactions`_. + +When creating a new request message, it has: + + :message id: see `Message ids`_ + :in reply to: unset (it's not a reply) + :to: either unset, or a specific Ksock id if the request + should fail if that Ksock is (no longer) the replier + for this message name + :from: unset (KBUS will set it) + :flags: the "needs a reply" flag should be set. + KBUS will set the "you need to reply" flag in the + copy of the message delivered to its replier. + :message name: as appropriate + :message data: as appropriate + +When receiving a request message, the WANT_YOU_TO_REPLY flag will be set if it +is this recipient's responsibility to reply. + +The Python interface provides a ``Request`` class to help in creating a +request message. + +When a request message is sent, it is an error if there is no replier bound to +that message name. + +The message will, as normal, be delivered to all listeners, and will have the +"needs a reply" flag set wherever it is received. However, only the copy of +the message received by the replier will be marked with the WANT_YOU_TO_REPLY +flag. + + So, if a particular file descriptor is bound as listener and replier + for '$.Fred', it will receive two copies of the original message (one + marked as needing reply from that file descriptor). However, when the + reply is sent, only the "plain" listener will receive a copy of the reply + message. + +Reply message +------------- +A reply message is the expected response after reading a request message. + +A reply message is distinguished by having a non-zero 'in reply to' value. + +Each reply message is in response to a specific request, as indicated by the +'in reply to' field in the message. + +The replier is helped to remember that it needs to reply to a request, because +the request has the WANT_YOU_TO_REPLY flag set. + +When a reply is sent, all listeners for that message name will receive it. +However, the original replier will not. + +When creating a new reply message, it has: + + :message id: see `Message ids`_ + :in reply to: the request message's 'message id' + :to: the request message's 'from' id + :from: unset (KBUS will set it) + :flags: typically unset, see `Message flags`_ + :message name: the request message's 'message name' + :message data: as appropriate + +The Python interface provides a ``Reply`` class to help in creating a reply +message, but more usefully there is also a ``reply_to`` function that creates +a Reply Message from the original Request. + +Status message +-------------- +KBUS generates Status messages (also sometimes referred to as "synthetic" +messages) when a request message has been successfully sent, but the replier +is unable to reply (for instance, because it has closed its Ksock). KBUS thus +uses a Status message to provide the "reply" that it guarantees the sender +will get. + +As you might expect, a KBUS status message is thus (technically) a reply +message. + +A status message looks like: + + :message id: as normal + :in reply to: the 'message id' of the message whose sending or + processing caused this message. + :to: the Ksock id of the recipient of the message + :from: the Ksock id of the sender of the message - this will + be 0 if the sender is KBUS itself (which is assumed for + most exceptions) + :flags: typically unset, see `Message flags`_ + :message name: for KBUS exceptions, a message name in '$.KBUS.*' + :message data: for KBUS exceptions, normally absent + +KBUS status messages always have '$.KBUS.' names (this may be a +multi-level ), and are always in response to a previous message, so +always have an 'in reply to'. + +Requests and Replies +-------------------- +KBUS guarantees that each Request will (eventually) be matched by a consequent +Reply (or Status [1]_) message, and only one such. + +The "normal" case is when the replier reads the request, and sends its own +reply back. + +If a Request message has been successfully SENT, there are the following other +cases to consider: + +1. The replier unbinds from that message name before reading the request + message from its queue. In this case, KBUS removes the message from the + repliers queue, and issues a "$.KBUS.Replier.Unbound" message. + +2. The replier closes itself (close the Ksock), but has not yet read the + message. In this case, KBUS issues a "$.KBUS.Replier.GoneAway" message. + +3. The replier closes itself (closes the Ksock), has read the message, but has + not yet (and now cannot) replied to it. In this case, KBUS issues a + "$.KBUS.Replier.Ignored" message. + +4. SEND did not complete, and the replier closes itself before the message can + be added to its message queue (by the POLL mechanism). In this case, KBUS + issues a "$.KBUS.Replier.Disappeared" message. + +5. SEND did not complete, and an error occurs when the POLL mechanims tries to + send the message. In this case, KBUS issues a "$.KBUS.ErrorSending" + message. + +In all these cases, the 'in_reply_to' field is set to the original request's +message id. In the first three cases, the 'from' field will be set to the +Ksock id of the (originally intended) replier. In the last two cases, that +information is not available, and a 'from' of 0 (indicating KBUS itself) is +used. + +.. [1] Remember that a Status message is essentially a specialisation of a + Reply message. + +.. note:: Limpets introduce some extra messages, which will be documented when + the proper Limpet documentation is written. + +KBUS end points - Ksocks +======================== +The KBUS devices +---------------- +Message interactions happen via the KBUS devices. Installing the KBUS kernel +module always creates ``/dev/kbus0``, it may also create ``/dev/kbus1``, and +so on. + + The number of devices to create is indicated by an argument at module + installation, for instance:: + + # insmod kbus.ko num_kbus_devices=10 + +Messages are sent by writing to a KBUS device, and received by reading from +the same device. A variety of useful ioctls are also provided. Each KBUS +device is independent - messages cannot be sent from ``/dev/kbus0`` to +``/dev/kbus1``, since there is no shared information. + +Ksocks +------ +Specifically, messages are written to and read from KBUS device file +descriptors. Each such is termed a *Ksock* - this is a simpler term than "file +descriptor", and has some resonance with "socket". + +Each Ksock may be any (one or more) of: + +* a Sender (opening the device for read/write) +* a Listener (only needing to open the device for read) +* a Replier (opening the device for read/write) + +Every Ksock has an id. This is a 32-bit unsigned number assigned by KBUS when +the device is opened. The value 0 is reserved for KBUS itself. + + The terms "listener id", "sender id", "replier id", etc., thus all refer + to a Ksock id, depending on what it is being used for. + +Senders +------- +Message senders are called "senders". A sender should open a Ksock for read +and write, as it may need to read replies and error/status messages. + +A message is sent by: + +1. Writing the message to the Ksock (using the standard ``write`` function) +2. Calling the SEND ioctl on the Ksock, to actually send the message. This + returns (via its arguments) the message id of the message sent. It also + returns status information about the send + + The status information is to be documented. + +The DISCARD ioctl can be used to "throw away" a partially written message, +before SEND has been called on it. + +If there are no listeners (of any type) bound to that message name, then the +message will be ignored. + +If the message is flagged as needing a reply, and there are no repliers bound +to that message name, then an error message will be sent to the sender, by +KBUS. + +It is not possible to send a message with a wildcard message name. + + As a restriction this makes the life of the implementor and documentor + easier. I believe it would also be confusing if provided. + +The sender does not need to bind to any message names in order to receive +error and status messages from KBUS. + +When a sender sends a Request, an internal note is made that it expects a +corresponding Reply (or possible a Status message from KBUS if the Replier +goes away or unbinds from that message name, before replying). A place for +that Reply is reserved in the sender's message queue. If the message queue +fills up (either with messages waiting to be read, or with reserved slots for +Replies), then the sender will not be able to send another Request until there +is room on the message queue again. + + Hopefully, this can be resolved by the sender reading a message off its + queue. However, if there are no messages to be read, and the queue is all + reserved for replies, the only solution is for the sender to wait for a + replier to send it something that it can then read. + +.. note:: What order do we describe things in? Don't forget: + + If the message being sent is a request, then the replier bound to that + message name will (presumably) write a reply to the request. Thus the normal + sequence for a request is likely to be: + + 1. write the request message + 2. read the reply + + The sender does *not* need to bind to anything in order to receive a reply to + a request it has sent. + + Of course, if a sender binds to listen to the name it uses for its + request, then it will get a copy of the request as sent, and it will + also get (an extra) copy of the reply. But see `Receiving messages once + only`_. + +Listeners +--------- +Message recipients are called "listeners". + +Listeners indicate that they want to receive particular messages, by using the +BIND ioctl on a Ksock to specify the name of the message that is to be +listened for. If the binding is to a wildcarded message name, then the +listener will receive all messages with names that match the wildcard. + +An ordinary listener will receive all messages with that name (sent to the +relevant Ksock). A listener may make more than one binding on the same Ksock +(indeed, it is allowed to bind to the same name more than once). + +Messages are received by: + +1. Using the NEXTMSG ioctl to request the next message (this also returns the + messages length in bytes) +2. Calling the standard ``read`` function to read the message data. + +If NEXTMSG is called again, the next message will be readied for reading, +whether the previous message has been read (or partially read) or not. + +If a listener no longer wants to receive a particular message name, then they +can unbind from it, using the UNBIND ioctl. The message name and flags used in +an UNBIND must match those in the corresponding BIND. Any messages in the +listener's message queue which match that unbinding will be removed from the +queue (i.e., the listener will not actually receive them). This does *not* +affect the message currently being read. + + Note that this has implication for binding and unbinding wildcards, + which must also match. + +Closing the Ksock also unbinds all the message bindings made on it. +It does not affect message bindings made on other Ksocks. + +Repliers +-------- +Repliers are a special sort of listener. + +For each message name, there may be a single "replier". A replier binds to a +message name in the same way as any other listener, but sets the "replier" +flag. If someone else has already bound to the same Ksock as a replier for +that message name, the request will fail. + +Repliers only receive Requests (messages that are marked as wanting a reply). + +A replier may (should? must?) reply to the request - this is done by sending +a Reply message through the Ksock from which the Request was read. + +It is perfectly legitimate to bind to a message as both replier and listener, +in which case two copies of the message will be read, once as replier, and +once as (just) listener (but see `Receiving messages once only`_). + + +When a request message is read by the appropriate replier, KBUS will mark +*that particular message* with the "you must reply" flag. This will not be set +on copies of that message read by any (non-replier) listeners. + + So, in the case where a Ksock is bound as replier and listener for the + same message name, only one of the two copies of the message received will + be marked as "you must reply". + +If a replier binds to a wildcarded message name, then they are the *default* +replier for any message names satisfying that wildcard. If another replier +binds to a more specific message name (matching that wildcard), +then the specific message name binding "wins" - the wildcard replier will no +longer receive that message name. + + In particular '$.Fred.Jim' is more specific than '$.Fred.%' which in turn + is more specific than '$.Fred.*' + +This means that if a wildcard replier wants to guarantee to see all the +messages matching their wildcard, they also need to bind as a listener for the +same wildcarded name. + +For example: + + Assume message names are of the form '$.Sensors.' or + '$.Sensors..'. + + Replier 1 binds to '$.Sensors.*'. They will be the default replier for + all sensor requests. + + Replier 2 binds to '$.Sensors.%'. They will take over as the default + replier for any room specific requests. + + Replier 3 binds to '$.Sensors.Kitchen.Temperature'. They will take over as + the replier for the kitchen temperature. + + So: + + - A message named '$.Sensors.Kitchen.Temperature' will go to replier 3. + - A message named '$.Sensors.Kitchen' or '$.Sensors.LivingRoom' will go to + replier 2. + - A message named '$.Sensors.LivingRoom.Temperature' will go to replier 1. + +When a Replier is closed (technically, when its ``release`` function is +called by the kernel) KBUS traverses its outstanding message queue, and for +each Request that has not been answered, generates a Status message saying +that the Replier has "GoneAway". + +Similarly, if a Replier unbinds from replying to a mesage, KBUS traverses its +outstanding message queue, and for each Request that has not been answered, it +generates a Status message saying that it has "Unbound" from being a replier +for that message name. It also forgets the message, which it is now not going +to reply to. + +Lastly, when a Replier is closed, if it has read any Requests (technically, +called NEXTMSG to pop them from the message queue), but not actually replied +to them, then KBUS will send an "Ignored" Status message for each such +Request. + +More information +================ +Stateful transactions +--------------------- +It is possible to make stateful message transactions, by: + +1. sending a Request +2. receiving the Reply, and noting the Ksock id of the replier +3. sending another Request to that specific replier +4. and so on + +Sending a request to a particular Ksock will fail if that Ksock is no longer +bound as replier to the relevant message name. This allows a sender to +guarantee that it is communicating with a particular instance of the replier +for a message name. + +Queues filling up +----------------- +Messages are sent by a mechanism which: + +1. Checks the message is plausible (it has a plausible message name, + and the right sort of "shape") +2. If the message is a Request, checks that the sender has room on its message + queue for the (eventual) Reply. +3. Finds the Ksock ids of all the listeners and repliers bound to that + messages name +4. Adds the message to the queue for each such listener/replier + +This can cause problems if one of the queues is already full (allowing +infinite expansion of queues would also cause problems, of couse). + +If a *sender* attempts to send a Request, but does not have room on its +message queue for the (corresponding) Reply, then the message will not be +sent, and the send will fail. Note that the message id will not be set, and +the blocking behaviours defined below do not occur. + +If a *replier* cannot receive a particular message, because its queue is full, +then the message will not be sent, and the send will fail with an error. This +does, however, set the message id (and thus the "last message id" on the +sender). + +Moreover, a sender can indicate if it wants a message to be: + +1. Added to all the listener queues, regardless, in which case it will block + until that can be done (ALL_OR_WAIT, sender blocks) +2. Added to all the listener queues, and fail if that can't be done + (ALL_OR_FAIL) +3. Added to all the listener queues that have room (the default) + +See `Message flags`_ for more details. + +Urgent messages +--------------- +Messages may be flagged urgent. In this case they will be added to the front +of the destination message queue, rather than the end - in other words, they +will be the next message to be "popped" by NEXTMSG. + +Note that this means that if two urgent messages are sent to the same target, +and *then* a NEXTMSG/read occurs, the second urgent message will be popped and +read first. + +Select, write/send and "next message", blocking +----------------------------------------------- +.. warning:: At the moment, ``read`` and ``write`` are always non-blocking. + +``read`` returns more of the currently selected message, or EOF if there is no +more of that message to read (and thus also if there is no currently selected +message). The NEXTMSG ioctl is used to select ("pop") the next message. + +``write`` writes to the end of the currently-being-written message. The +DISCARD ioctl can be used to discard the data written so far, and the SEND +ioctl to send the (presumably completed message). Whilst the message is being +sent, it is not possible to use ``write``. + +Note that if SEND is used to send a Request, then KBUS ensures that there will +always be either a Reply or a Status message in response to that request. + +Specifically, if: + +1. The Replier "goes away" (and its "release" function is called) before + reading the Request (specifically, before calling NEXTMSG to pop it from + the message queue) +2. The Replier "goes away" (and its "release" function is called) before + replying to a Request that it has already read (i.e., used NEXTMSG to pop + from the message queue) +3. The Replier unbinds from that Request message name before reading the + Request (with the same caveat on what that means) +4. Select/poll attempts to send the Request, and discovers that the + Replier has disappeared since the initial SEND +5. Select/poll attempts to send the Request, and some other error occurs + +then KBUS will "reply" with an appropriate Status message. + +-------------------------------------------------- + +KBUS support its own particular variation on blocking of message sending. + +First of all, it supports use of "select" to determine if there are any +messages waiting to be read. So, for instance (in Python):: + + with Ksock(0,'rw') as sender: + with Ksock(0,'r') as listener: + (r,w,x) = select.select([listener],[],[],0) + assert r == [] + + listener.bind('$.Fred') + msg = Announcement('$.Fred','data') + sender.send_msg(msg) + + (r,w,x) = select.select([listener],[],[],0) + assert r == [listener] + +This simply checks if there is a message in the Ksock's message list, waiting +to be "popped" with NEXTMSG. + +Secondly, ``write``, SEND and DISCARD interact in what is hoped to be a +sensible manner. Specifically: + +* When SEND (i.e., the SEND ioctl) is called, KBUS can either: + + 1. Succeed in sending the message. The Ksock is now ready for ``write`` to + be called on it again. + 2. Failed in sending the message (possibly, if the message was a Request, + with EADDRNOTAVAIL, indicating that there is no Replier for that + Request). The Ksock is now ready for ``write`` to be called on it again. + 3. If the message was marked ALL_OR_WAIT, then it may fail with EAGAIN. + In this case, the Ksock is still in sending state, and an attempt to + call ``write`` will fail (with EALREADY). The caller can either use + DISCARD to discard the message, or use select/poll to wait for the + message to finish sending. + +Thus "select" for the write case checks whether it is allowed to call +"write" - for instance:: + + with Ksock(0,'rw') as sender: + write_list = [sender] + with Ksock(0,'r') as listener1: + write_list= [sender,listener1] + read_list = [listener1] + + (r,w,x) = select.select(read_list,write_list,[],0) + assert r == [] + assert w == [sender] + assert x == [] + + with Ksock(0,'rw') as listener2: + write_list.append(listener2) + read_list.append(listener2) + + (r,w,x) = select.select(read_list,write_list,[],0) + assert r == [] + assert len(w) == 2 + assert sender in w + assert listener2 in w + assert x == [] + +Receiving messages once only +---------------------------- +In normal usage (and by default), if a Ksock binds to a message name multiple +times, it will receive multiple copies of a message. This can happen: + +* explicitly (the Ksock deliberately and explicitly binds to the same name + more than once, seeking this effect). +* as a result of binding to a message name and a wildcard that includes the + same name, or two overlapping wildcards. +* as a result of binding as Replier to a name, and also as Listener to the + same name (possibly via a wildcard). In this case, multiple copies will + only be received when a Request with that name is made. + +Several programmers have complained that the last case, in particular, is very +inconvenient, and thus the "receive a message once only" facility has been +added. + +Using the MSGONCEONLY IOCTL, it is possible to tell a Ksock that only one copy +of a particular message should be received, even if multiple are "due". In the +case of the Replier/Listener copies, it will always be the message to which +the Replier should reply (the one with WANT_YOU_TO_REPLY set) that will be +received. + +Please use this facility with care, and only if you really need it. + +IOCTLS +------ +The KBUS ioctls are defined (with explanatory comments) in the kernel module +header file (``kbus_defns.h``). They are: + +:RESET: Currently has no effect +:BIND: Bind to a particular message name (possibly as replier). +:UNBIND: Unbind from a binding - must match exactly. +:KSOCKID: Determine the Ksock id of the Ksock used +:REPLIER: Determine who is bound as replier to a particular message + name. This returns 0 or the Ksock id of the replier. +:NEXTMSG: Pop the next message from the Ksock's message queue, ready + for reading (with ``read``), and return its length (in bytes). + If there is no next message, return a length of 0. + The length is always the length of an "entire" message (see + `Message implementation`_). +:LENLEFT: Determine how many bytes of the message currently being read + are still to read. +:SEND: Send the current outstanding message for this Ksock (i.e., the + bytes written to the Ksock since the last SEND or DISCARD). + Return the message id of the message, and maybe other status + information. +:DISCARD: Discard (throw away) the current outstanding message for this + Ksock (i.e., any bytes written to the Ksock since the last + SEND or DISCARD). +:LASTSENT: Determine the message id of the last message SENT on this + Ksock. +:MAXMSGS: Set the maximum length of the (read) message queue for this + KSOCK, and return the actual length that is set. An attempt + to set the queue length to 0 will just return the current + queue length. +:NUMMSGS: Determine how many messages are outstanding in this Ksock's + read queue. +:UNREPLIEDTO: Determines how many Requests (marked "WANT_YOU_TO_REPLY") + this Ksock still needs to reply to. This is primarily a + development tool. +:MSGONLYONCE: Determines whether only one copy of a message will be + received, even if the message name is bound to multiple times. + May also be used to query the current state. +:VERBOSE: Determines whether verbose kernel messages should be output or + not. Affects the *device* (the entire Ksock). + May also be used to query the current state. +:NEWDEVICE: Requests another KBUS device (``/dev/kbus/``). The next + KBUS device number (up to a maximum of 255) will be allocated. + Returns the new device number. +:REPORTREPLIERBINDS: Request synthetic messages announcing Replier BIND/UNBIND + events. These are messages named "$.KBUS.ReplierBindEvent", + and are the only predefined messages with data. + Both Python and C bindings provide a useful function to + extract the ``is_bind``, ``binder`` and ``name`` values from + the data. + +/proc/kbus/bindings +------------------- +``/proc/kbus/bindings`` is a debugging aid for reporting the listener id, +exclusive flag and message name for each binding, for each kbus device. + +An example might be:: + + $ cat /proc/kbus/bindings + # is bound to in as for + 1: 1 22158 R $.Sensors.* + 1: 2 22158 R $.Sensors.Kitchen.Temperature + 1: 3 22158 L $.Sensors.* + 13: 4 22159 L $.Jim.* + 13: 1 22159 R $.Fred + 13: 1 22159 L $.Jim + 13: 14 23021 L $.Jim.* + +This describes two KBUS devices (``/dev/kbus1`` and ``/dev/kbus13``). + +The first has bindings on Ksock ids 1, 2 and 3, for the given message names. The +"R" indicates a replier binding, the "L" indicates a listener (non-replier) +binding. + +The second has bindings on Ksock ids 4, 1 and 14. The order of the bindings +reported is *not* particularly significant. + +Note that there is no communication between the two devices, so Ksock id 1 on +device 1 is not related to (and has no commonality with) Ksock id 1 on device +13. + +/proc/kbus/stats +---------------- +``/proc/kbus/stats`` is a debugging aid for reporting various statistics about +the KBUS devices and the Ksocks open on them. + +An example might be:: + + $ cat /proc/kbus/stats + dev 0: next file 5 next msg 8 unsent unbindings 0 + ksock 4 last msg 0:7 queue 1 of 100 + read byte 0 of 0, wrote byte 52 (max 60), sending + outstanding requests 0 (size 16, max 0), unsent replies 0 (max 0) + ksock 3 last msg 0:5 queue 0 of 1 + read byte 0 of 0, wrote byte 0 (max 0), not sending + outstanding requests 1 (size 16, max 0), unsent replies 0 (max 0) + +or:: + + $ cat /proc/kbus/stats + dev 0: next file 4 next msg 101 unsent unbindings 0 + ksock 3 last msg 0:0 queue 100 of 100 + read byte 0 of 0, wrote byte 0 (max 0), not sending + outstanding requests 0 (size 16, max 0), unsent replies 0 (max 0) + ksock 2 last msg 0:100 queue 0 of 100 + read byte 0 of 0, wrote byte 0 (max 0), not sending + outstanding requests 100 (size 102, max 92), unsent replies 0 (max 0) + + +Error numbers +------------- +The following error numbers get special use. In Python, they are all returned +as values inside the IOError exception. + + Since we're trying to fit into the normal Un*x convention that negative + values are error numbers, and since Un*x defines many of these for us, + it is natural to make use of the relevant definitions. However, this also + means that we are often using them in an unnatural sense. I've tried to + make the error numbers used bear at least a vague relationship to their + (mis)use in KBUS. + +:EADDRINUSE: On attempting to bind a message name as replier: There is + already a replier bound for this message +:EADDRNOTAVAIL: On attempting to send a Request message: There is no replier + bound for this message's name. + + On attempting to send a Reply message: The sender of the + original request (i.e., the Ksock mentioned as the ``to`` + in the Reply) is no longer connected. +:EALREADY: On attempting to write to a Ksock, when a previous send has + returned EAGAIN. Either DISCARD the message, or use + select/poll to wait for the send to complete, and write to be + allowed. +:EBADMSG: On attempting to bind, unbind or send a message: The message + name is not valid. On sending, this can also be because the + message name is a wildcard. +:EBUSY: On attempting to send, then: + + 1. For a request, the replier's message queue is full. + 2. For any message, with ALL_OR_FAIL set, one of the + targetted listener/replier queues was full. + +:ECONNREFUSED: On attempting to send a Reply, the intended recipient (the + notional original sender of the Request) is not expecting + a Reply with that message id in its 'in_reply_to'. Or, in + other words, this appears to be an attempt to reply to the + wrong message id or the wrong Ksock. +:EINVAL: Something went wrong (generic error). +:EMSGSIZE: On attempting to write a message: Data was written after + the end of the message (i.e., after the final end guard + of the message). +:ENAMETOOLONG: On attempting to bind, unbind or send a message: The message + name is too long. +:ENOENT: On attempting to open a Ksock: There is no such device + (normally because one has tried to open, for instance, + '/dev/kbus9' when there are only 3 KBUS devices). +:ENOLCK: On attempting to send a Request, when there is not enough room + in the sender's message queue to guarantee that it can + receive a reply for every Request already sent, *plus* this + one. If there are oustanding messages in the sender's message + queue, then the solution is to read some of them. Otherwise, + the sender will have to wait until one of the Repliers + replies to a previous Request (or goes away and KBUS replies + for it). + + When this error is received, the send has failed (just as if + the message was invalid). The sender is not left in "sending" + state, nor has the message been assigned a message id. + + Note that this is *not* EAGAIN, since we do not want to block + the sender (in the SEND) if it is up to the sender to perform + a read to sort things out. + +:ENOMSG: On attempting to send, when there is no message waiting to be + sent (either because there has been no write since the last + send, or because the message being written has been + discarded). +:EPIPE: On attempting to send 'to' a specific replier, the replier + with that id is no longer bound to the given message's name. + +:EFAULT: Memory allocation, copy from user space, or other such failed. This + is normally very bad, it should not happen, UNLESS it is the result + of calling an ioctl, when it indicates that the ioctl argument + cannot be accessed. + +:ENOMEM: Memory allocation failed (return NULL). This is normally very bad, + it should not happen. + +:EAGAIN: On attempting to send, the message being sent had ALL_OR_WAIT set, + and one of the targetted listener/replier queues was full. + + On attempting to unbind when Replier Bind Events have been + requested, one or more of the KSocks bound to receive + "$.KBUS.ReplierBindEvent" messages has a full message queue, + and thus cannot receive the unbind event. The unbind has not been + done. + +In the ``utils`` directory of the KBUS sources, there is a script called +``errno.py`` which takes an ``errno`` integer or name and prints out both the +"normal" meaning of that error number, and also (if there is one) the KBUS use +of it. For instance:: + + $ errno.py 1 + Error 1 (0x1) is EPERM: Operation not permitted + $ + $ errno.py EPIPE + EPIPE is error 32 (0x20): Broken pipe + + KBUS: + On attempting to send 'to' a specific replier, the replier with that id + is no longer bound to the given message's name. + diff --git a/include/linux/kbus_defns.h b/include/linux/kbus_defns.h new file mode 100644 index 0000000..6f12f54 --- /dev/null +++ b/include/linux/kbus_defns.h @@ -0,0 +1,666 @@ +/* Kbus kernel module external headers + * + * This file provides the definitions (datastructures and ioctls) needed to + * communicate with the KBUS character device driver. + */ + +/* + * ***** BEGIN LICENSE BLOCK ***** + * Version: MPL 1.1 + * + * The contents of this file are subject to the Mozilla Public License Version + * 1.1 (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * http://www.mozilla.org/MPL/ + * + * Software distributed under the License is distributed on an "AS IS" basis, + * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License + * for the specific language governing rights and limitations under the + * License. + * + * The Original Code is the KBUS Lightweight Linux-kernel mediated + * message system + * + * The Initial Developer of the Original Code is Kynesim, Cambridge UK. + * Portions created by the Initial Developer are Copyright (C) 2009 + * the Initial Developer. All Rights Reserved. + * + * Contributor(s): + * Kynesim, Cambridge UK + * Tony Ibbs + * + * Alternatively, the contents of this file may be used under the terms of the + * GNU Public License version 2 (the "GPL"), in which case the provisions of + * the GPL are applicable instead of the above. If you wish to allow the use + * of your version of this file only under the terms of the GPL and not to + * allow others to use your version of this file under the MPL, indicate your + * decision by deleting the provisions above and replace them with the notice + * and other provisions required by the GPL. If you do not delete the + * provisions above, a recipient may use your version of this file under either + * the MPL or the GPL. + * + * ***** END LICENSE BLOCK ***** + */ + +#ifndef _kbus_defns +#define _kbus_defns + +#if !__KERNEL__ && defined(__cplusplus) +extern "C" { +#endif + +#if __KERNEL__ +#include +#include +#else +#include +#include +#endif + +/* + * A message id is made up of two fields. + * + * If the network id is 0, then it is up to us (KBUS) to assign the + * serial number. In other words, this is a local message. + * + * If the network id is non-zero, then this message is presumed to + * have originated from another "network", and we preserve both the + * network id and the serial number. + * + * The message id {0,0} is special and reserved (for use by KBUS). + */ +struct kbus_msg_id { + uint32_t network_id; + uint32_t serial_num; +}; + +/* + * kbus_orig_from is used for the "originally from" and "finally to" ids + * in the message header. These in turn are used when messages are + * being sent between KBUS systems (via KBUS "Limpets"). KBUS the kernel + * module transmits them, unaltered, but does not use them (although + * debug messages may report them). + * + * An "originally from" or "finally to" id is made up of two fields, the + * network id (which indicates the Limpet, if any, that originally gated the + * message), and a local id, which is the Ksock id of the original sender + * of the message, on its local KBUS. + * + * If the network id is 0, then the "originally from" id is not being used. + * + * Limpets and these fields are discussed in more detail in the userspace + * KBUS documentation - see http://kbus-messaging.org/ for pointers to + * more information. + */ +struct kbus_orig_from { + uint32_t network_id; + uint32_t local_id; +}; + +/* When the user asks to bind a message name to an interface, they use: */ +struct kbus_bind_request { + uint32_t is_replier; /* are we a replier? */ + uint32_t name_len; + char *name; +}; + +/* When the user requests the id of the replier to a message, they use: */ +struct kbus_bind_query { + uint32_t return_id; + uint32_t name_len; + char *name; +}; + +/* When the user writes/reads a message, they use: */ +struct kbus_message_header { + /* + * The guards + * ---------- + * + * * 'start_guard' is notionally "Kbus", and 'end_guard' (the 32 bit + * word after the rest of the message datastructure) is notionally + * "subK". Obviously that depends on how one looks at the 32-bit + * word. Every message datastructure shall start with a start guard + * and end with an end guard. + * + * These provide some help in checking that a message is well formed, + * and in particular the end guard helps to check for broken length + * fields. + * + * - 'id' identifies this particular message. + * + * When a user writes a new message, they should set this to {0,0}. + * KBUS will then set a new message id for the message. + * + * When a user reads a message, this will have been set by KBUS. + * + * When a user replies to a message, they should copy this value + * into the 'in_reply_to' field, so that the recipient will know + * what message this was a reply to. + * + * - 'in_reply_to' identifies the message this is a reply to. + * + * This shall be set to {0,0} unless this message *is* a reply to a + * previous message. In other words, if this value is non-0, then + * the message *is* a reply. + * + * - 'to' is who the message is to be sent to. + * + * When a user writes a new message, this should normally be set + * to {0,0}, meaning "anyone listening" (but see below if "state" + * is being maintained). + * + * When replying to a message, it shall be set to the 'from' value + * of the orginal message. + * + * When constructing a request message (a message wanting a reply), + * the user can set it to a specific replier id, to produce a stateful + * request. This is normally done by copying the 'from' of a previous + * Reply from the appropriate replier. When such a message is sent, + * if the replier bound (at that time) does not have that specific + * id, then the send will fail. + * + * Note that if 'to' is set, then 'orig_from' should also be set. + * + * - 'from' indicates who sent the message. + * + * When a user is writing a new message, they should set this + * to {0,0}. + * + * When a user is reading a message, this will have been set + * by KBUS. + * + * When a user replies to a message, the reply should have its + * 'to' set to the original messages 'from', and its 'from' set + * to {0,0} (see the "hmm" caveat under 'to' above, though). + * + * - 'orig_from' and 'final_to' are used when Limpets are mediating + * KBUS messages between KBUS devices (possibly on different + * machines). See the description by the datastructure definition + * above. The KBUS kernel preserves and propagates their values, + * but does not alter or use them. + * + * - 'extra' is currently unused, and KBUS will set it to zero. + * Future versions of KBUS may treat it differently. + * + * - 'flags' indicates the type of message. + * + * When a user writes a message, this can be used to indicate + * that: + * + * * the message is URGENT + * * a reply is wanted + * + * When a user reads a message, this indicates if: + * + * * the message is URGENT + * * a reply is wanted + * + * When a user writes a reply, this field should be set to 0. + * + * The top half of the 'flags' is not touched by KBUS, and may + * be used for any purpose the user wishes. + * + * - 'name_len' is the length of the message name in bytes. + * + * This must be non-zero. + * + * - 'data_len' is the length of the message data in bytes. It may be + * zero if there is no data. + * + * - 'name' is a pointer to the message name. This should be null + * terminated, as is the normal case for C strings. + * + * NB: If this is zero, then the name will be present, but after + * the end of this datastructure, and padded out to a multiple of + * four bytes (see kbus_entire_message). When doing this padding, + * remember to allow for the terminating null byte. If this field is + * zero, then 'data' shall also be zero. + * + * - 'data' is a pointer to the data. If there is no data (if + * 'data_len' is zero), then this shall also be zero. The data is + * not touched by KBUS, and may include any values. + * + * NB: If this is zero, then the data will occur immediately + * after the message name, padded out to a multiple of four bytes. + * See the note for 'name' above. + * + */ + uint32_t start_guard; + struct kbus_msg_id id; /* Unique to this message */ + struct kbus_msg_id in_reply_to; /* Which message this is a reply to */ + uint32_t to; /* 0 (empty) or a replier id */ + uint32_t from; /* 0 (KBUS) or the sender's id */ + struct kbus_orig_from orig_from; /* Cross-network linkage */ + struct kbus_orig_from final_to; /* Cross-network linkage */ + uint32_t extra; /* ignored field - future proofing */ + uint32_t flags; /* Message type/flags */ + uint32_t name_len; /* Message name's length, in bytes */ + uint32_t data_len; /* Message length, also in bytes */ + char *name; + void *data; + uint32_t end_guard; +}; + +#define KBUS_MSG_START_GUARD 0x7375624B +#define KBUS_MSG_END_GUARD 0x4B627573 + +/* + * When a message is returned by 'read', it is actually returned using the + * following datastructure, in which: + * + * - 'header.name' will point to 'rest[0]' + * - 'header.data' will point to 'rest[(header.name_len+3)/4]' + * + * followed by the name (padded to 4 bytes, remembering to allow for the + * terminating null byte), followed by the data (padded to 4 bytes) followed by + * (another) end_guard. + */ +struct kbus_entire_message { + struct kbus_message_header header; + uint32_t rest[]; +}; + +/* + * We limit a message name to at most 1000 characters (some limit seems + * sensible, after all) + */ +#define KBUS_MAX_NAME_LEN 1000 + +/* + * The length (in bytes) of the name after padding, allowing for a terminating + * null byte. + */ +#define KBUS_PADDED_NAME_LEN(name_len) (4 * ((name_len + 1 + 3) / 4)) + +/* + * The length (in bytes) of the data after padding + */ +#define KBUS_PADDED_DATA_LEN(data_len) (4 * ((data_len + 3) / 4)) + +/* + * Given name_len (in bytes) and data_len (in bytes), return the + * length of the appropriate kbus_entire_message_struct, in bytes + * + * Note that we're allowing for a zero byte after the end of the message name. + * + * Remember that "sizeof" doesn't count the 'rest' field in our message + * structure. + */ +#define KBUS_ENTIRE_MSG_LEN(name_len, data_len) \ + (sizeof(struct kbus_entire_message) + \ + KBUS_PADDED_NAME_LEN(name_len) + \ + KBUS_PADDED_DATA_LEN(data_len) + 4) + +/* + * The message name starts at entire->rest[0]. + * The message data starts after the message name - given the message + * name's length (in bytes), that is at index: + */ +#define KBUS_ENTIRE_MSG_DATA_INDEX(name_len) ((name_len+1+3)/4) +/* + * Given the message name length (in bytes) and the message data length (also + * in bytes), the index of the entire message end guard is thus: + */ +#define KBUS_ENTIRE_MSG_END_GUARD_INDEX(name_len, data_len) \ + ((name_len+1+3)/4 + (data_len+3)/4) + +/* + * Find a pointer to the message's name. + * + * It's either the given name pointer, or just after the header (if the pointer + * is NULL) + */ +static inline char *kbus_msg_name_ptr(const struct kbus_message_header + *hdr) +{ + if (hdr->name) { + return hdr->name; + } else { + struct kbus_entire_message *entire; + entire = (struct kbus_entire_message *)hdr; + return (char *)&entire->rest[0]; + } +} + +/* + * Find a pointer to the message's data. + * + * It's either the given data pointer, or just after the name (if the pointer + * is NULL) + */ +static inline void *kbus_msg_data_ptr(const struct kbus_message_header + *hdr) +{ + if (hdr->data) { + return hdr->data; + } else { + struct kbus_entire_message *entire; + uint32_t data_idx; + + entire = (struct kbus_entire_message *)hdr; + data_idx = KBUS_ENTIRE_MSG_DATA_INDEX(hdr->name_len); + return (void *)&entire->rest[data_idx]; + } +} + +/* + * Find a pointer to the message's (second/final) end guard. + */ +static inline uint32_t *kbus_msg_end_ptr(struct kbus_entire_message + *entire) +{ + uint32_t end_guard_idx = + KBUS_ENTIRE_MSG_END_GUARD_INDEX(entire->header.name_len, + entire->header.data_len); + return (uint32_t *) &entire->rest[end_guard_idx]; +} + +/* + * Things KBUS changes in a message + * -------------------------------- + * In general, KBUS leaves the content of a message alone. However, it does + * change: + * + * - the message id (if id.network_id is unset - it assigns a new serial + * number unique to this message) + * - the from id (if from.network_id is unset - it sets the local_id to + * indicate the Ksock this message was sent from) + * - the KBUS_BIT_WANT_YOU_TO_REPLY bit in the flags (set or cleared + * as appropriate) + * - the SYNTHETIC bit, which KBUS will always unset in a user message + */ + +/* + * Flags for the message 'flags' word + * ---------------------------------- + * The KBUS_BIT_WANT_A_REPLY bit is set by the sender to indicate that a + * reply is wanted. This makes the message into a request. + * + * Note that setting the WANT_A_REPLY bit (i.e., a request) and + * setting 'in_reply_to' (i.e., a reply) is bound to lead to + * confusion, and the results are undefined (i.e., don't do it). + * + * The KBUS_BIT_WANT_YOU_TO_REPLY bit is set by KBUS on a particular message + * to indicate that the particular recipient is responsible for replying + * to (this instance of the) message. Otherwise, KBUS clears it. + * + * The KBUS_BIT_SYNTHETIC bit is set by KBUS when it generates a synthetic + * message (an exception, if you will), for instance when a replier has + * gone away and therefore a reply will never be generated for a request + * that has already been queued. + * + * Note that KBUS does not check that a sender has not set this + * on a message, but doing so may lead to confusion. + * + * The KBUS_BIT_URGENT bit is set by the sender if this message is to be + * treated as urgent - i.e., it should be added to the *front* of the + * recipient's message queue, not the back. + * + * Send flags + * ========== + * There are two "send" flags, KBUS_BIT_ALL_OR_WAIT and KBUS_BIT_ALL_OR_FAIL. + * Either one may be set, or both may be unset. + * + * If both bits are set, the message will be rejected as invalid. + * + * Both flags are ignored in reply messages (i.e., messages with the + * 'in_reply_to' field set). + * + * If both are unset, then a send will behave in the default manner. That is, + * the message will be added to a listener's queue if there is room but + * otherwise the listener will (silently) not receive the message. + * + * (Obviously, if the listener is a replier, and the message is a request, + * then a KBUS message will be synthesised in the normal manner when a + * request is lost.) + * + * If the KBUS_BIT_ALL_OR_WAIT bit is set, then a send should block until + * all recipients can be sent the message. Specifically, before the message is + * sent, all recipients must have room on their message queues for this + * message, and if they do not, the send will block until there is room for the + * message on all the queues. + * + * If the KBUS_BIT_ALL_OR_FAIL bit is set, then a send should fail if all + * recipients cannot be sent the message. Specifically, before the message is + * sent, all recipients must have room on their message queues for this + * message, and if they do not, the send will fail. + */ + +/* + * When a $.KBUS.ReplierBindEvent message is constructed, we use the + * following to encapsulate its data. + * + * This indicates whether it is a bind or unbind event, who is doing the + * bind or unbind, and for what message name. The message name is padded + * out to a multiple of four bytes, allowing for a terminating null byte, + * but the name length is the length without said padding (so, in C terms, + * strlen(name)). + * + * As for the message header data structure, the actual data "goes off the end" + * of the datastructure. + */ +struct kbus_replier_bind_event_data { + uint32_t is_bind; /* 1=bind, 0=unbind */ + uint32_t binder; /* Ksock id of binder */ + uint32_t name_len; /* Length of name */ + uint32_t rest[]; /* Message name */ +}; + +#if !__KERNEL__ +#define BIT(num) (((unsigned)1) << (num)) +#endif + +#define KBUS_BIT_WANT_A_REPLY BIT(0) +#define KBUS_BIT_WANT_YOU_TO_REPLY BIT(1) +#define KBUS_BIT_SYNTHETIC BIT(2) +#define KBUS_BIT_URGENT BIT(3) + +#define KBUS_BIT_ALL_OR_WAIT BIT(8) +#define KBUS_BIT_ALL_OR_FAIL BIT(9) + +/* + * Standard message names + * ====================== + * KBUS itself has some predefined message names. + * + * Synthetic Replies with no data + * ------------------------------ + * These are sent to the original Sender of a Request when KBUS knows that the + * Replier is not going to Reply. In all cases, you can identify which message + * they concern by looking at the "in_reply_to" field: + * + * * Replier.GoneAway - the Replier has gone away before reading the Request. + * * Replier.Ignored - the Replier has gone away after reading a Request, but + * before replying to it. + * * Replier.Unbound - the Replier has unbound (as Replier) from the message + * name, and is thus not going to reply to this Request in its unread message + * queue. + * * Replier.Disappeared - the Replier has disappeared when an attempt is made + * to send a Request whilst polling (i.e., after EAGAIN was returned from an + * earlier attempt to send a message). This typically means that the Ksock + * bound as Replier closed. + * * ErrorSending - an unexpected error occurred when trying to send a Request + * to its Replier whilst polling. + * + * Synthetic Announcements with no data + * ------------------------------------ + * * UnbindEventsLost - sent (instead of a Replier Bind Event) when the unbind + * events "set aside" list has filled up, and thus unbind events have been + * lost. + */ +#define KBUS_MSG_NAME_REPLIER_GONEAWAY "$.KBUS.Replier.GoneAway" +#define KBUS_MSG_NAME_REPLIER_IGNORED "$.KBUS.Replier.Ignored" +#define KBUS_MSG_NAME_REPLIER_UNBOUND "$.KBUS.Replier.Unbound" +#define KBUS_MSG_NAME_REPLIER_DISAPPEARED "$.KBUS.Replier.Disappeared" +#define KBUS_MSG_NAME_ERROR_SENDING "$.KBUS.ErrorSending" +#define KBUS_MSG_NAME_UNBIND_EVENTS_LOST "$.KBUS.UnbindEventsLost" + +/* + * Replier Bind Event + * ------------------ + * This is the only message name for which KBUS generates data -- see + * kbus_replier_bind_event_data. It is also the only message name which KBUS + * does not allow binding to as a Replier. + * + * This is the message that is sent when a Replier binds or unbinds to another + * message name, if the KBUS_IOC_REPORTREPLIERBINDS ioctl has been used to + * request such notification. + */ +#define KBUS_MSG_NAME_REPLIER_BIND_EVENT "$.KBUS.ReplierBindEvent" + +#define KBUS_IOC_MAGIC 'k' /* 0x6b - which seems fair enough for now */ +/* + * RESET: reserved for future use + */ +#define KBUS_IOC_RESET _IO(KBUS_IOC_MAGIC, 1) +/* + * BIND - bind a Ksock to a message name + * arg: struct kbus_bind_request, indicating what to bind to + * retval: 0 for success, negative for failure + */ +#define KBUS_IOC_BIND _IOW(KBUS_IOC_MAGIC, 2, char *) +/* + * UNBIND - unbind a Ksock from a message id + * arg: struct kbus_bind_request, indicating what to unbind from + * retval: 0 for success, negative for failure + */ +#define KBUS_IOC_UNBIND _IOW(KBUS_IOC_MAGIC, 3, char *) +/* + * KSOCKID - determine a Ksock's Ksock id + * + * The network_id for the current Ksock is, by definition, 0, so we don't need + * to return it. + * + * arg (out): uint32_t, indicating this Ksock's local_id + * retval: 0 for success, negative for failure + */ +#define KBUS_IOC_KSOCKID _IOR(KBUS_IOC_MAGIC, 4, char *) +/* + * REPLIER - determine the Ksock id of the replier for a message name + * arg: struct kbus_bind_query + * + * - on input, specify the message name to ask about. + * - on output, KBUS fills in the relevant Ksock id in the return_value, + * or 0 if there is no bound replier + * + * retval: 0 for success, negative for failure + */ +#define KBUS_IOC_REPLIER _IOWR(KBUS_IOC_MAGIC, 5, char *) +/* + * NEXTMSG - pop the next message from the read queue + * arg (out): uint32_t, number of bytes in the next message, 0 if there is no + * next message + * retval: 0 for success, negative for failure + */ +#define KBUS_IOC_NEXTMSG _IOR(KBUS_IOC_MAGIC, 6, char *) +/* + * LENLEFT - determine how many bytes are left to read of the current message + * arg (out): uint32_t, number of bytes left, 0 if there is no current read + * message + * retval: 1 if there was a message, 0 if there wasn't, negative for failure + */ +#define KBUS_IOC_LENLEFT _IOR(KBUS_IOC_MAGIC, 7, char *) +/* + * SEND - send the current message + * arg (out): struct kbus_msg_id, the message id of the sent message + * retval: 0 for success, negative for failure + */ +#define KBUS_IOC_SEND _IOR(KBUS_IOC_MAGIC, 8, char *) +/* + * DISCARD - discard the message currently being written (if any) + * arg: none + * retval: 0 for success, negative for failure + */ +#define KBUS_IOC_DISCARD _IO(KBUS_IOC_MAGIC, 9) +/* + * LASTSENT - determine the message id of the last message SENT + * arg (out): struct kbus_msg_id, {0,0} if there was no last message + * retval: 0 for success, negative for failure + */ +#define KBUS_IOC_LASTSENT _IOR(KBUS_IOC_MAGIC, 10, char *) +/* + * MAXMSGS - set the maximum number of messages on a Ksock read queue + * arg (in): uint32_t, the requested length of the read queue, or 0 to just + * request how many there are + * arg (out): uint32_t, the length of the read queue after this call has + * succeeded + * retval: 0 for success, negative for failure + */ +#define KBUS_IOC_MAXMSGS _IOWR(KBUS_IOC_MAGIC, 11, char *) +/* + * NUMMSGS - determine how many messages are in the read queue for this Ksock + * arg (out): uint32_t, the number of messages in the read queue. + * retval: 0 for success, negative for failure + */ +#define KBUS_IOC_NUMMSGS _IOR(KBUS_IOC_MAGIC, 12, char *) +/* + * UNREPLIEDTO - determine the number of requests (marked "WANT_YOU_TO_REPLY") + * which we still need to reply to. + * arg(out): uint32_t, said number + * retval: 0 for success, negative for failure + */ +#define KBUS_IOC_UNREPLIEDTO _IOR(KBUS_IOC_MAGIC, 13, char *) +/* + * MSGONLYONCE - should we receive a message only once? + * + * This IOCTL tells a Ksock whether it should only receive a particular message + * once, even if it is both a Replier and Listener for the message (in which + * case it will always get the message as Replier, if appropriate), or if it is + * registered as multiple Listeners for the message. + * + * arg(in): uint32_t, 1 to change to "only once", 0 to change to the default, + * 0xFFFFFFFF to just return the current/previous state. + * arg(out): uint32_t, the previous state. + * retval: 0 for success, negative for failure (-EINVAL if arg in was not one + * of the specified values) + */ +#define KBUS_IOC_MSGONLYONCE _IOWR(KBUS_IOC_MAGIC, 14, char *) +/* + * VERBOSE - should KBUS output verbose "printk" messages (for this device)? + * + * This IOCTL tells a Ksock whether it should output debugging messages. It is + * only effective if the kernel module has been built with the VERBOSE_DEBUGGING + * flag set. + * + * arg(in): uint32_t, 1 to change to "verbose", 0 to change to "quiet", + * 0xFFFFFFFF to just return the current/previous state. + * arg(out): uint32_t, the previous state. + * retval: 0 for success, negative for failure (-EINVAL if arg in was not one + * of the specified values) + */ +#define KBUS_IOC_VERBOSE _IOWR(KBUS_IOC_MAGIC, 15, char *) + +/* + * NEWDEVICE - request another KBUS device (/dev/kbus). + * + * The next device number (up to a maximum of 255) will be allocated. + * + * arg(out): uint32_t, the new device number () + * retval: 0 for success, negative for failure + */ +#define KBUS_IOC_NEWDEVICE _IOR(KBUS_IOC_MAGIC, 16, char *) + +/* + * REPORTREPLIERBINDS - request synthetic messages announcing Replier + * bind/unbind events. + * + * If this flag is set, then when someone binds or unbinds to a message name as + * a Replier, KBUS will send out a synthetic Announcement of this fact. + * + * arg(in): uint32_t, 1 to change to "report", 0 to change to "do not report", + * 0xFFFFFFFF to just return the current/previous state. + * arg(out): uint32_t, the previous state. + * retval: 0 for success, negative for failure (-EINVAL if arg in was not one + * of the specified values) + */ +#define KBUS_IOC_REPORTREPLIERBINDS _IOWR(KBUS_IOC_MAGIC, 17, char *) + +/* If adding another IOCTL, remember to increment the next number! */ +#define KBUS_IOC_MAXNR 17 + +#if !__KERNEL__ && defined(__cplusplus) +} +#endif + +#endif /* _kbus_defns */ diff --git a/init/Kconfig b/init/Kconfig index c972899..a31a6fe 100644 --- a/init/Kconfig +++ b/init/Kconfig @@ -339,6 +339,8 @@ config AUDIT_TREE depends on AUDITSYSCALL select FSNOTIFY +source "ipc/Kconfig" + source "kernel/irq/Kconfig" menu "RCU Subsystem" @@ -1305,3 +1307,4 @@ config PADATA bool source "kernel/Kconfig.locks" + diff --git a/ipc/Kconfig b/ipc/Kconfig new file mode 100644 index 0000000..46ebcda --- /dev/null +++ b/ipc/Kconfig @@ -0,0 +1,99 @@ +config KBUS + tristate "KBUS messaging system" + default m + ---help--- + KBUS is a lightweight messaging system, particularly aimed + at embedded platforms. This option provides the kernel support + for mediating messages between client processes. + + If you want KBUS support, you should say Y here. + + This support can also be built as a module. If so, the module + will be called kbus. + +if KBUS + +config KBUS_DEBUG + bool "Make KBUS debugging messages available" + default y + ---help--- + This is the master switch for KBUS debug kernel messages - + if turned off, all debug messages will be compiled out. + + In order for debugging messages to be emitted, they must + be enabled per-device with the KBUS_IOC_VERBOSE ioctl, + or by default by CONFIG_KBUS_DEBUG_DEFAULT_VERBOSE. + + If unsure, say Y. + +config KBUS_DEBUG_DEFAULT_VERBOSE + bool "Output KBUS debug messages by default" + depends on KBUS_DEBUG + default n + ---help--- + This switch is the default setting for whether KBUS devices will + emit debugging messages. Note that debug messages may be turned + on and off per-device at runtime with the KBUS_IOC_VERBOSE ioctl. + + If unsure, say N. + +config KBUS_DEF_NUM_DEVICES + int "Number of KBUS devices to auto-create" + default 1 + range 1 KBUS_MAX_NUM_DEVICES + ---help--- + This specifies the number of KBUS devices that will be automatically + created when the kbus subsystem initialises (when the module is + is loaded or the kernel booted, as appropriate). + + If kbus is built as a module, this number may also be given as a + parameter, for example kbus_num_devices=5. + +config KBUS_MAX_NUM_DEVICES + int "Maximum number of KBUS devices" + default 256 + range 1 2147483647 + # We don't impose a limit on the max, so if you've got enough + # RAM the only practical limit will be the (int) minor count + # passed to __register_chrdev_region. + ---help--- + Specify the maximum number of KBUS devices to support. + Note that this setting controls the size of an array of pointers + to in-kernel kbus structs; reducing it only saves a tiny amount + of RAM. + +config KBUS_DEF_MAX_MESSAGES + int "Default KBUS message queue size limit" + default 100 + range 1 2147483647 + ---help--- + Specify the default recipient message queue size limit. + This default is applied to all recipients (clients) whenever they + open or reopen a KBUS device node. + + Clients sending messages may specify their desired behaviour in + the event that any of the recipient(s)' message queues is full; + if a sender's own queue is full, it may not send a message + flagged as a Request. Refer to the documentation ("Queues filling + up") for details. + + Clients may change their own queue size limits at any time with the + KBUS_IOC_MAXMSGS ioctl. + +config KBUS_MAX_UNSENT_UNBIND_MESSAGES + int "Maximum number of unsent KBUS unbind event messages" + default 1000 + range 1 2147483647 + ---help--- + KBUS devices may request (by ioctl) that they want to receive + notifications when listeners unbind. If such a notification happens + at a time when the device's message queue is full, it is instead + saved internally and delivered later. This setting limits the number + of messages which may be queued internally in that way; if the + limit is reached, a special "there were more unbind events than + we were able to deliver" message is queued for that listener, + and no more internal events are sent to them until that message + has been delivered. + +endif # KBUS + diff --git a/ipc/Makefile b/ipc/Makefile index 9075e17..87b7430 100644 --- a/ipc/Makefile +++ b/ipc/Makefile @@ -9,4 +9,5 @@ obj_mq-$(CONFIG_COMPAT) += compat_mq.o obj-$(CONFIG_POSIX_MQUEUE) += mqueue.o msgutil.o $(obj_mq-y) obj-$(CONFIG_IPC_NS) += namespace.o obj-$(CONFIG_POSIX_MQUEUE_SYSCTL) += mq_sysctl.o +obj-$(CONFIG_KBUS) += kbus.o diff --git a/ipc/kbus.c b/ipc/kbus.c new file mode 100644 index 0000000..b5b81df --- /dev/null +++ b/ipc/kbus.c @@ -0,0 +1,5120 @@ +/* Kbus kernel module + * + * This is a character device driver, providing the messaging support + * for kbus. + */ + +/* + * ***** BEGIN LICENSE BLOCK ***** + * Version: MPL 1.1 + * + * The contents of this file are subject to the Mozilla Public License Version + * 1.1 (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * http://www.mozilla.org/MPL/ + * + * Software distributed under the License is distributed on an "AS IS" basis, + * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License + * for the specific language governing rights and limitations under the + * License. + * + * The Original Code is the KBUS Lightweight Linux-kernel mediated + * message system + * + * The Initial Developer of the Original Code is Kynesim, Cambridge UK. + * Portions created by the Initial Developer are Copyright (C) 2009 + * the Initial Developer. All Rights Reserved. + * + * Contributor(s): + * Kynesim, Cambridge UK + * Tony Ibbs + * + * Alternatively, the contents of this file may be used under the terms of the + * GNU Public License version 2 (the "GPL"), in which case the provisions of + * the GPL are applicable instead of the above. If you wish to allow the use + * of your version of this file only under the terms of the GPL and not to + * allow others to use your version of this file under the MPL, indicate your + * decision by deleting the provisions above and replace them with the notice + * and other provisions required by the GPL. If you do not delete the + * provisions above, a recipient may use your version of this file under either + * the MPL or the GPL. + * + * ***** END LICENSE BLOCK ***** + */ + +#include +#include + +#include +#include /* device classes (for hotplugging), &c */ +#include /* registering character devices */ +#include +#include /* for isalnum */ +#include +#include /* for kmalloc, etc. */ +#include /* for current->pid */ +#include /* copy_*_user() functions */ +#include /* PAGE_SIZE */ +#include +#include + +#include +#include "kbus_internal.h" + +static int kbus_num_devices = CONFIG_KBUS_DEF_NUM_DEVICES; + +/* Who we are -- devices */ +static int kbus_major; /* 0 => We'll go for dynamic allocation */ +static int kbus_minor; /* 0 => We're happy to start with device 0 */ + +/* We can't need more than 8 characters of padding, by definition! */ +static char *static_zero_padding = "\0\0\0\0\0\0\0\0"; +static uint32_t static_end_guard = KBUS_MSG_END_GUARD; + +/* Our actual devices, 0 through kbus_num_devices-1 */ +static struct kbus_dev **kbus_devices; + +static struct class *kbus_class_p; +static struct device **kbus_class_devices; + +/* /proc */ +static struct proc_dir_entry *kbus_proc_dir; +static struct proc_dir_entry *kbus_proc_file_bindings; +static struct proc_dir_entry *kbus_proc_file_stats; + +/* ========================================================================= */ + +/* As few foreshadowings as I can get away with */ +static struct kbus_private_data *kbus_find_open_ksock(struct kbus_dev *dev, + uint32_t id); + +/* I really want this function where it is in the code, so need to foreshadow */ +static int kbus_setup_new_device(int which); + +/* More or less ditto */ +static int32_t kbus_write_to_recipients(struct kbus_private_data *priv, + struct kbus_dev *dev, + struct kbus_msg *msg); + +static void kbus_forget_unbound_unsent_unbind_msgs(struct kbus_private_data + *priv, + struct kbus_message_binding + *binding); + +static int kbus_alloc_ref_data(struct kbus_private_data *priv, + uint32_t data_len, + struct kbus_data_ptr **ret_ref_data); +/* ========================================================================= */ + +/* What's the symbolic name of a message part? */ +static const char *kbus_msg_part_name(enum kbus_msg_parts p) +{ + switch (p) { + case KBUS_PART_HDR: return "HDR"; + case KBUS_PART_NAME: return "NAME"; + case KBUS_PART_NPAD: return "NPAD"; + case KBUS_PART_DATA: return "DATA"; + case KBUS_PART_DPAD: return "DPAD"; + case KBUS_PART_FINAL_GUARD: return "FINAL"; + } + + printk(KERN_ERR "kbus: unhandled enum lookup %d in kbus_msg_part_name " + "- memory corruption?", p); + return "???"; +} + +/* What's the symbolic name of a replier type? */ +__maybe_unused +static const char *kbus_replier_type_name(enum kbus_replier_type t) +{ + switch (t) { + case UNSET: return "UNSET"; + case WILD_STAR: return "WILD_STAR"; + case WILD_PERCENT: return "WILD_PERCENT"; + case SPECIFIC: return "SPECIFIC"; + } + printk(KERN_ERR "kbus: unhandled enum lookup %d in " + "kbus_replier_type_name - memory corruption?", t); + return "???"; +} + +/* + * Wrap a set of data pointers and lengths in a reference + */ +static struct kbus_data_ptr *kbus_wrap_data_in_ref(int as_pages, + unsigned num_parts, + unsigned long *parts, + unsigned *lengths, + unsigned last_page_len) +{ + struct kbus_data_ptr *new = NULL; + + new = kmalloc(sizeof(*new), GFP_KERNEL); + if (!new) + return NULL; + + new->as_pages = as_pages; + new->parts = parts; + new->lengths = lengths; + new->num_parts = num_parts; + new->last_page_len = last_page_len; + + kref_init(&new->refcount); + + kbus_maybe_dbg_refcount("kbus: <00 ref %p now %d>\n", + new->parts, atomic_read(&new->refcount.refcount)); + return new; +} + +/* + * Increment the reference count for our pointer. + * + * Returns the (same) reference, for convenience. + */ +static struct kbus_data_ptr *kbus_raise_data_ref(struct kbus_data_ptr *refdata) +{ + if (refdata != NULL) { + kref_get(&refdata->refcount); + kbus_maybe_dbg_refcount("kbus: \n", + refdata->parts, + atomic_read(&refdata->refcount.refcount)); + } + return refdata; +} + +/* + * Data release callback for data reference pointers. Called when the reference + * count says to... + */ +static void kbus_release_data_ref(struct kref *ref) +{ + struct kbus_data_ptr *refdata = container_of(ref, + struct kbus_data_ptr, + refcount); + kbus_maybe_dbg_refcount("kbus: RELEASE DATA\n"); + if (refdata->parts == NULL) { + /* Not that I think this can happen */ + printk(KERN_ERR "kbus: Removing data reference," + " but data ptr already freed\n"); + } else { + int jj; + if (refdata->as_pages) + for (jj = 0; jj < refdata->num_parts; jj++) + free_page((unsigned long)refdata->parts[jj]); + else + for (jj = 0; jj < refdata->num_parts; jj++) + kfree((void *)refdata->parts[jj]); + kfree(refdata->parts); + kfree(refdata->lengths); + refdata->parts = NULL; + refdata->lengths = NULL; + } + kfree(refdata); +} + +/* + * Forget a reference to our pointer, and if no-one cares anymore, free it and + * its contents. + */ +static void kbus_lower_data_ref(struct kbus_data_ptr *refdata) +{ + if (refdata == NULL) + return; + + kref_put(&refdata->refcount, kbus_release_data_ref); + + kbus_maybe_dbg_refcount("kbus: \n", + refdata->parts, atomic_read(&refdata->refcount.refcount)); +} + +/* + * Wrap a string in a reference. Does not take a copy of the string, + * but note that the release mechanism (triggered when there are no more + * references to the string) *will* free it. + */ +static struct kbus_name_ptr *kbus_wrap_name_in_ref(char *str) +{ + struct kbus_name_ptr *new = NULL; + + new = kmalloc(sizeof(*new), GFP_KERNEL); + if (!new) + return NULL; + + new->name = str; + kref_init(&new->refcount); + + kbus_maybe_dbg_refcount("kbus: <00 ref '%s' now %d>\n", + new->name, atomic_read(&new->refcount.refcount)); + return new; +} + +/* + * Increment the reference count for a string reference + * + * Returns the (same) reference, for convenience. + */ +static struct kbus_name_ptr *kbus_raise_name_ref(struct kbus_name_ptr *refname) +{ + if (refname != NULL) { + kref_get(&refname->refcount); + kbus_maybe_dbg_refcount("kbus: \n", + refname->name, atomic_read(&refname->refcount.refcount)); + } + return refname; +} + +/* + * Data release callback for string reference pointers. + * Called when the reference count says to... + */ +static void kbus_release_name_ref(struct kref *ref) +{ + struct kbus_name_ptr *refname = container_of(ref, + struct kbus_name_ptr, + refcount); + kbus_maybe_dbg_refcount("kbus: RELEASE NAME\n"); + kbus_maybe_dbg_refcount("kbus: refname is %p\n", refname); + kbus_maybe_dbg_refcount("kbus: refname->name is %p\n", + refname->name); + if (refname->name == NULL) { + /* Not that I think this can happen */ + printk(KERN_ERR "kbus: Removing name reference," + " but name ptr already freed\n"); + } else { + kfree(refname->name); + refname->name = NULL; + } + + kfree(refname); +} + +/* + * Forget a reference to our string, and if no-one cares anymore, free it and + * its contents. + */ +static void kbus_lower_name_ref(struct kbus_name_ptr *refname) +{ + if (refname == NULL) + return; + + kbus_maybe_dbg_refcount("kbus: \n", + refname->name, atomic_read(&refname->refcount.refcount) - 1); + + kref_put(&refname->refcount, kbus_release_name_ref); +} + +/* + * Return a stab at the next size for an array + */ +static uint32_t kbus_next_size(uint32_t old_size) +{ + if (old_size < 16) + /* For very small numbers, just double */ + return old_size << 1; + /* Otherwise, try something like the mechanism used for Python + * lists - doubling feels a bit over the top */ + return old_size + (old_size >> 3); +} + +/* Determine (and return) the next message serial number */ +static uint32_t kbus_next_serial_num(struct kbus_dev *dev) +{ + if (dev->next_msg_serial_num == 0) + dev->next_msg_serial_num++; + return dev->next_msg_serial_num++; +} + +static int kbus_same_message_id(struct kbus_msg_id *msg_id, + uint32_t network_id, uint32_t serial_num) +{ + return msg_id->network_id == network_id && + msg_id->serial_num == serial_num; +} + +static int kbus_init_msg_id_memory(struct kbus_private_data *priv) +{ + struct kbus_msg_id_mem *mem = &priv->outstanding_requests; + struct kbus_msg_id *ids; + + ids = kmalloc(sizeof(*ids) * KBUS_INIT_MSG_ID_MEMSIZE, GFP_KERNEL); + if (!ids) + return -ENOMEM; + + memset(ids, 0, sizeof(*ids) * KBUS_INIT_MSG_ID_MEMSIZE); + + mem->count = 0; + mem->max_count = 0; + mem->ids = ids; + mem->size = KBUS_INIT_MSG_ID_MEMSIZE; + return 0; +} + +static void kbus_empty_msg_id_memory(struct kbus_private_data *priv) +{ + struct kbus_msg_id_mem *mem = &priv->outstanding_requests; + + if (mem->ids == NULL) + return; + + kfree(mem->ids); + mem->ids = NULL; + mem->size = 0; + mem->max_count = 0; + mem->count = 0; +} + +/* + * Note we don't worry about whether the id is already in there - if + * the user cares, that's up to them (I don't think I do) + */ +static int kbus_remember_msg_id(struct kbus_private_data *priv, + struct kbus_msg_id *id) +{ + struct kbus_msg_id_mem *mem = &priv->outstanding_requests; + int ii, which; + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u Remembering outstanding" + " request %u:%u (count->%d)\n", + priv->dev->index, priv->id, + id->network_id, id->serial_num, mem->count + 1); + + /* First, try for an empty slot we can re-use */ + for (ii = 0; ii < mem->size; ii++) { + if (kbus_same_message_id(&mem->ids[ii], 0, 0)) { + which = ii; + goto done; + } + + } + /* Otherwise, give in and use a new one */ + if (mem->count == mem->size) { + uint32_t old_size = mem->size; + uint32_t new_size = kbus_next_size(old_size); + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u XXX outstanding" + " request array size %u -> %u\n", + priv->dev->index, priv->id, old_size, new_size); + + mem->ids = krealloc(mem->ids, + new_size * sizeof(struct kbus_msg_id), + GFP_KERNEL); + if (!mem->ids) + return -EFAULT; + for (ii = old_size; ii < new_size; ii++) { + mem->ids[ii].network_id = 0; + mem->ids[ii].serial_num = 0; + } + mem->size = new_size; + which = mem->count; + } + which = mem->count; +done: + mem->ids[which] = *id; + mem->count++; + if (mem->count > mem->max_count) + mem->max_count = mem->count; + return 0; +} + +/* Returns 0 if we found it, -1 if we couldn't find it */ +static int kbus_find_msg_id(struct kbus_private_data *priv, + struct kbus_msg_id *id) +{ + struct kbus_msg_id_mem *mem = &priv->outstanding_requests; + int ii; + for (ii = 0; ii < mem->size; ii++) { + if (!kbus_same_message_id(&mem->ids[ii], + id->network_id, id->serial_num)) + continue; + kbus_maybe_dbg(priv->dev, "kbus: %u/%u Found outstanding " + "request %u:%u (count=%d)\n", + priv->dev->index, priv->id, id->network_id, + id->serial_num, mem->count); + return 0; + } + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Could not find outstanding " + "request %u:%u (count=%d)\n", + priv->dev->index, priv->id, id->network_id, + id->serial_num, mem->count); + return -1; +} + +/* Returns 0 if we found and forgot it, -1 if we couldn't find it */ +static int kbus_forget_msg_id(struct kbus_private_data *priv, + struct kbus_msg_id *id) +{ + struct kbus_msg_id_mem *mem = &priv->outstanding_requests; + int ii; + for (ii = 0; ii < mem->size; ii++) { + if (!kbus_same_message_id(&mem->ids[ii], + id->network_id, id->serial_num)) + continue; + + mem->ids[ii].network_id = 0; + mem->ids[ii].serial_num = 0; + mem->count--; + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Forgot outstanding " + "request %u:%u (count<-%d)\n", + priv->dev->index, priv->id, id->network_id, + id->serial_num, mem->count); + + return 0; + } + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Could not forget outstanding " + "request %u:%u (count<-%d)\n", + priv->dev->index, priv->id, id->network_id, + id->serial_num, mem->count); + return -1; +} + +/* A message is a reply iff 'in_reply_to' is non-zero */ +static int kbus_message_is_reply(struct kbus_msg *msg) +{ + return !kbus_same_message_id(&msg->in_reply_to, 0, 0); +} + +/* + * Build a KBUS synthetic message/exception. We assume no data. + * + * The message built is a 'pointy' message. + * + * 'msg_name' is copied. + * + * Use kbus_free_message() to free this message when it is finished with. + */ +static struct kbus_msg +*kbus_build_kbus_message(struct kbus_dev *dev, + char *msg_name, + uint32_t from, + uint32_t to, struct kbus_msg_id in_reply_to) +{ + struct kbus_msg *new_msg; + struct kbus_name_ptr *name_ref; + + size_t msg_name_len = strlen(msg_name); + char *msg_name_copy; + + new_msg = kmalloc(sizeof(*new_msg), GFP_KERNEL); + if (!new_msg) { + printk(KERN_ERR "kbus: Cannot kmalloc synthetic message\n"); + return NULL; + } + + msg_name_copy = kmalloc(msg_name_len + 1, GFP_KERNEL); + if (!msg_name_copy) { + printk(KERN_ERR + "kbus: Cannot kmalloc synthetic message's name\n"); + kfree(new_msg); + return NULL; + } + + strncpy(msg_name_copy, msg_name, msg_name_len); + msg_name_copy[msg_name_len] = '\0'; + + name_ref = kbus_wrap_name_in_ref(msg_name_copy); + if (!name_ref) { + printk(KERN_ERR + "kbus: Cannot kmalloc synthetic message's string ref\n"); + kfree(new_msg); + kfree(msg_name_copy); + return NULL; + } + + memset(new_msg, 0, sizeof(*new_msg)); + + new_msg->from = from; + new_msg->to = to; + new_msg->in_reply_to = in_reply_to; + new_msg->flags = KBUS_BIT_SYNTHETIC; + new_msg->name_ref = name_ref; + new_msg->name_len = msg_name_len; + + new_msg->id.serial_num = kbus_next_serial_num(dev); + + return new_msg; +} + +/* + * Given a message name, is it valid? + * + * We have nothing to say on maximum length. + * + * Returns 0 if it's OK, 1 if it's naughty + */ +static int kbus_bad_message_name(char *name, size_t name_len) +{ + size_t ii; + int dot_at = 1; + + if (name_len < 3) + return 1; + + if (name == NULL || name[0] != '$' || name[1] != '.') + return 1; + + if (name[name_len - 2] == '.' && name[name_len - 1] == '*') + name_len -= 2; + else if (name[name_len - 2] == '.' && name[name_len - 1] == '%') + name_len -= 2; + + if (name[name_len - 1] == '.') + return 1; + + for (ii = 2; ii < name_len; ii++) { + if (name[ii] == '.') { + if (dot_at == ii - 1) + return 1; + dot_at = ii; + } else if (!isalnum(name[ii])) + return 1; + } + return 0; +} + +/* + * Is a message name wildcarded? + * + * We assume it is already checked to be a valid name + * + * Returns 1 if it is, 0 if not. In other words, returns 1 + * if the name is not a valid destination. + */ +static int kbus_wildcarded_message_name(char *name, size_t name_len) +{ + return name[name_len - 1] == '*' || name[name_len - 1] == '%'; +} + +/* + * Is a message name legitimate for writing/sending? + * + * This is an omnibus call of the last two checks, with error output. + * + * Returns 0 if it's OK, 1 if it's naughty + */ +static int kbus_invalid_message_name(char *name, size_t name_len) +{ + if (kbus_bad_message_name(name, name_len)) { + printk(KERN_ERR "kbus: pid %u [%s]" + " (send) message name '%.*s' is not allowed\n", + current->pid, current->comm, (int)name_len, name); + return 1; + } + if (kbus_wildcarded_message_name(name, name_len)) { + printk(KERN_ERR "kbus: pid %u [%s]" + " (send) sending to wildcards not allowed, " + "message name '%.*s'\n", + current->pid, current->comm, (int)name_len, name); + return 1; + } + return 0; +} + +/* + * Does this message name match the given binding? + * + * The binding may be a normal message name, or a wildcard. + * + * We assume that both names are legitimate. + */ +static int kbus_message_name_matches(char *name, size_t name_len, char *other) +{ + size_t other_len = strlen(other); + + if (other[other_len - 1] == '*' || other[other_len - 1] == '%') { + char *rest = name + other_len - 1; + size_t rest_len = name_len - other_len + 1; + + /* + * If we have '$.Fred.*', then we need at least '$.Fred.X' + * to match + */ + if (name_len < other_len) + return false; + /* + * Does the name match all of the wildcard except the + * last character? + */ + if (strncmp(other, name, other_len - 1)) + return false; + + /* '*' matches anything at all, so we're done */ + if (other[other_len - 1] == '*') + return true; + + /* '%' only matches if we don't have another dot */ + if (strnchr(rest, rest_len, '.')) + return false; + else + return true; + } else { + if (name_len != other_len) + return false; + else + return !strncmp(name, other, name_len); + } +} + +/* + * Check if a message read by kbus_write() is well formed + * + * Return 0 if a message is well-formed, negative otherwise. + */ +static int kbus_check_message_written(struct kbus_write_msg *this) +{ + struct kbus_message_header *user_msg = + (struct kbus_message_header *)&this->user_msg; + + if (this == NULL) { + printk(KERN_ERR "kbus: pid %u [%s]" + " Tried to check NULL message\n", + current->pid, current->comm); + return -EINVAL; + } + + if (user_msg->start_guard != KBUS_MSG_START_GUARD) { + printk(KERN_ERR "kbus: pid %u [%s]" + " message start guard is %08x, not %08x", + current->pid, current->comm, + user_msg->start_guard, KBUS_MSG_START_GUARD); + return -EINVAL; + } + if (user_msg->end_guard != KBUS_MSG_END_GUARD) { + printk(KERN_ERR "kbus: pid %u [%s]" + " message end guard is %08x, not %08x\n", + current->pid, current->comm, + user_msg->end_guard, KBUS_MSG_END_GUARD); + return -EINVAL; + } + + if (user_msg->name_len == 0) { + printk(KERN_ERR "kbus: pid %u [%s]" + " Message name length is 0\n", + current->pid, current->comm); + return -EINVAL; + } + if (user_msg->name_len > KBUS_MAX_NAME_LEN) { + printk(KERN_ERR "kbus: pid %u [%s]" + " Message name length is %u, more than %u\n", + current->pid, current->comm, + user_msg->name_len, KBUS_MAX_NAME_LEN); + return -ENAMETOOLONG; + } + + if (user_msg->name == NULL) { + if (user_msg->data != NULL) { + printk(KERN_ERR "kbus: pid %u [%s]" + " Message name is inline, data is not\n", + current->pid, current->comm); + return -EINVAL; + } + } else { + if (user_msg->data == NULL && user_msg->data_len != 0) { + printk(KERN_ERR "kbus: pid %u [%s]" + " Message data is inline, name is not\n", + current->pid, current->comm); + return -EINVAL; + } + } + + if (user_msg->data_len == 0 && user_msg->data != NULL) { + printk(KERN_ERR "kbus: pid %u [%s]" + " Message data length is 0, but data pointer is set\n", + current->pid, current->comm); + return -EINVAL; + } + + /* It's not legal to set both ALL_OR_WAIT and ALL_OR_FAIL */ + if ((user_msg->flags & KBUS_BIT_ALL_OR_WAIT) && + (user_msg->flags & KBUS_BIT_ALL_OR_FAIL)) { + printk(KERN_ERR "kbus: pid %u [%s]" + " Message cannot have both ALL_OR_WAIT and " + "ALL_OR_FAIL set\n", + current->pid, current->comm); + return -EINVAL; + } + return 0; +} + +/* + * Output a description of an in-kernel message + */ +static void kbus_maybe_report_message(struct kbus_dev *dev __maybe_unused, + char *kern_prefix __maybe_unused, + struct kbus_msg *msg __maybe_unused) +{ + if (msg->data_len) { + struct kbus_data_ptr *data_p = msg->data_ref; + uint8_t *part0 __maybe_unused = (uint8_t *) data_p->parts[0]; + kbus_maybe_dbg(dev, "%skbus: === %u:%u '%.*s'" + " to %u from %u in-reply-to %u:%u orig %u,%u " + "final %u:%u flags %04x:%04x" + " data/%u %02x.%02x.%02x.%02x\n", + kern_prefix, + msg->id.network_id, msg->id.serial_num, + msg->name_len, msg->name_ref->name, + msg->to, msg->from, + msg->in_reply_to.network_id, msg->in_reply_to.serial_num, + msg->orig_from.network_id, msg->orig_from.local_id, + msg->final_to.network_id, msg->final_to.local_id, + (msg->flags & 0xFFFF0000) >> 4, + (msg->flags & 0x0000FFFF), msg->data_len, + data_p->num_parts, part0[0], part0[1], part0[2], + part0[3]); + } else { + kbus_maybe_dbg(dev, "%skbus: === %u:%u '%.*s'" + " to %u from %u in-reply-to %u:%u orig %u,%u " + "final %u,%u flags %04x:%04x\n", + kern_prefix, + msg->id.network_id, msg->id.serial_num, + msg->name_len, msg->name_ref->name, + msg->to, msg->from, + msg->in_reply_to.network_id, msg->in_reply_to.serial_num, + msg->orig_from.network_id, msg->orig_from.local_id, + msg->final_to.network_id, msg->final_to.local_id, + (msg->flags & 0xFFFF0000) >> 4, + (msg->flags & 0x0000FFFF)); + } +} + +static void kbus_report_write_msg(struct kbus_private_data *priv) +{ + kbus_maybe_dbg_write(priv->dev, + "kbus: %u/%u WRITE MSG finished %u local %u msg %p " + "which %d pos %u ref %p part %u\n", + priv->dev->index, priv->id, priv->write.is_finished, + priv->write.pointers_are_local, priv->write.msg, + priv->write.which, priv->write.pos, priv->write.ref_data, + priv->write.ref_data_index); + if (priv->write.msg) + kbus_maybe_dbg_write(priv->dev, + "kbus: msg name %p data %p\n", + priv->write.msg->name_ref, + priv->write.msg->data_ref); +} + +/* + * Copy a message, doing whatever is deemed necessary. + * + * Copies the message header, and also copies the message name and any + * data. The message must be a 'pointy' message with reference counted + * name and data. + */ +static struct kbus_msg *kbus_copy_message(struct kbus_msg *old_msg) +{ + struct kbus_msg *new_msg; + + new_msg = kmalloc(sizeof(*new_msg), GFP_KERNEL); + if (!new_msg) { + printk(KERN_ERR + "kbus: Cannot kmalloc copy of message header\n"); + return NULL; + } + if (!memcpy(new_msg, old_msg, sizeof(*new_msg))) { + printk(KERN_ERR "kbus: Cannot copy message header\n"); + kfree(new_msg); + return NULL; + } + + /* In case of error before we're finished... */ + new_msg->name_ref = NULL; + new_msg->data_ref = NULL; + + new_msg->name_ref = kbus_raise_name_ref(old_msg->name_ref); + + if (new_msg->data_len) + /* Take a new reference to the data */ + new_msg->data_ref = kbus_raise_data_ref(old_msg->data_ref); + return new_msg; +} + +/* + * Free a message. + * + * Also dereferences the message name and any message data. + */ +static void kbus_free_message(struct kbus_msg *msg) +{ + if (msg->name_ref) + kbus_lower_name_ref(msg->name_ref); + msg->name_len = 0; + msg->name_ref = NULL; + + if (msg->data_len && msg->data_ref) + kbus_lower_data_ref(msg->data_ref); + + msg->data_len = 0; + msg->data_ref = NULL; + kfree(msg); +} + +static void kbus_empty_read_msg(struct kbus_private_data *priv) +{ + struct kbus_read_msg *this = &(priv->read); + int ii; + + kbus_maybe_dbg_write(priv->dev, + "kbus: %u/%u kbus_empty_read_msg ------------\n", + priv->dev->index, priv->id); + if (this->msg == NULL) + kbus_maybe_dbg_write(priv->dev, "kbus: ( is NULL)\n"); + + if (this->msg) { + kbus_free_message(this->msg); + this->msg = NULL; + } + + for (ii = 0; ii < KBUS_NUM_PARTS; ii++) { + this->parts[ii] = NULL; + this->lengths[ii] = 0; + } + this->which = 0; + this->pos = 0; + this->ref_data_index = 0; +} + +static void kbus_empty_write_msg(struct kbus_private_data *priv) +{ + struct kbus_write_msg *this = &priv->write; + kbus_maybe_dbg_write(priv->dev, + "kbus: %u/%u kbus_empty_write_msg ------------\n", + priv->dev->index, priv->id); + kbus_report_write_msg(priv); + if (this->msg) { + kbus_free_message(this->msg); + this->msg = NULL; + } + + if (this->ref_name) { + kbus_lower_name_ref(this->ref_name); + this->ref_name = NULL; + } + + if (this->ref_data) { + kbus_lower_data_ref(this->ref_data); + this->ref_data = NULL; + } + + this->is_finished = false; + this->pos = 0; + this->which = 0; + kbus_report_write_msg(priv); + kbus_maybe_dbg_write(priv->dev, + "kbus: %u/%u ------------ kbus_empty_write_msg\n", + priv->dev->index, priv->id); +} + +/* + * Copy the given message, and add it to the end of the queue. + * + * This is the *only* way of adding a message to a queue. It shall remain so. + * + * We assume the message has been checked for sanity. + * + * 'msg' is the message to add to the queue. + * + * 'binding' is a pointer to the KBUS message name binding that caused the + * message to be added. + * + * 'for_replier' is true if this particular message is being pushed to the + * message's replier's queue. Specifically, it's true if this is a Reply + * to this Ksock, or a Request aimed at this Ksock (as Replier). + * + * Returns 0 if all goes well, or -EFAULT/-ENOMEM if we can't allocate + * datastructures. + * + * May also return negative values if the message is mis-named or malformed, + * at least at the moment. + */ +static int kbus_push_message(struct kbus_private_data *priv, + struct kbus_msg *msg, + struct kbus_message_binding *binding, + int for_replier) +{ + struct list_head *queue = &priv->message_queue; + struct kbus_msg *new_msg = NULL; + struct kbus_message_queue_item *item; + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Pushing message onto queue (%s)\n", + priv->dev->index, priv->id, + for_replier ? "replier" : "listener"); + + /* + * 1. Check to see if this Ksock has the "only one copy + * of a message" flag set. + * 2. If it does, check if our message (id) is already on + * the queue, and if it is, just skip adding it. + * + * (this means if the Ksock was destined to get the message + * several times, either as Replier and Listener, or as + * multiple Listeners to the same message name, it will only + * get it once, for this "push") + * + * If "for_replier" is set we necessarily push the message - see below. + */ + if (priv->messages_only_once && !for_replier) { + /* + * 1. We've been asked to only send one copy of a message + * to each Ksock that should receive it. + * 2. This is not a Reply (to our Ksock) or a Request (to + * our Ksock as Replier) + * + * So, given that, has a message with that id already been + * added to the message queue? + * + * (Note that if a message would be included because of + * multiple message name bindings, we do not say anything + * about which binding we will actually add the message + * for - so unbinding later on may or may not cause a + * message to go away, in this case.) + */ + if (kbus_same_message_id(&priv->msg_id_just_pushed, + msg->id.network_id, + msg->id.serial_num)) { + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Ignoring message " + "under 'once only' rule\n", + priv->dev->index, priv->id); + return 0; + } + } + + new_msg = kbus_copy_message(msg); + if (!new_msg) + return -EFAULT; + + item = kmalloc(sizeof(*item), GFP_KERNEL); + if (!item) { + printk(KERN_ERR "kbus: Cannot kmalloc new message item\n"); + kbus_free_message(new_msg); + return -ENOMEM; + } + kbus_maybe_report_message(priv->dev, KERN_DEBUG, new_msg); + + if (for_replier && (KBUS_BIT_WANT_A_REPLY & msg->flags)) { + /* + * This message wants a reply, and is for the message's + * replier, so they need to be told that they are to reply to + * this message + */ + new_msg->flags |= KBUS_BIT_WANT_YOU_TO_REPLY; + kbus_maybe_dbg(priv->dev, + "kbus: Setting WANT_YOU_TO_REPLY, " + "flags %08x\n", + new_msg->flags); + } else { + /* + * The recipient is *not* the replier for this message, + * so it is not responsible for replying. + */ + new_msg->flags &= ~KBUS_BIT_WANT_YOU_TO_REPLY; + } + + /* And join it up... */ + item->msg = new_msg; + item->binding = binding; + + /* By default, we're using the list as a FIFO, so we want to add our + * new message to the end (just before the first item). However, if the + * URGENT flag is set, then we instead want to add it to the start. + */ + if (msg->flags & KBUS_BIT_URGENT) { + kbus_maybe_dbg(priv->dev, "kbus: Message is URGENT\n"); + list_add(&item->list, queue); + } else { + list_add_tail(&item->list, queue); + } + + priv->message_count++; + priv->msg_id_just_pushed = msg->id; + + if (!kbus_same_message_id(&msg->in_reply_to, 0, 0)) { + /* + * If it's a reply (and this will include a synthetic reply, + * since we're checking the "in_reply_to" field) then the + * original sender has now had its request satisfied. + */ + int retval = kbus_forget_msg_id(priv, &msg->in_reply_to); + + if (retval) + /* But there's not much we can do about it */ + printk(KERN_ERR + "kbus: %u/%u Error forgetting " + "outstanding request %u:%u\n", + priv->dev->index, priv->id, + msg->in_reply_to.network_id, + msg->in_reply_to.serial_num); + } + + /* And indicate that there is something available to read */ + wake_up_interruptible(&priv->read_wait); + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Leaving %d message%s in queue\n", + priv->dev->index, priv->id, priv->message_count, + priv->message_count == 1 ? "" : "s"); + + return 0; +} + +/* + * Generate a synthetic message, and add it to the recipient's message queue. + * + * This is to be used when a Reply is not going to be generated + * by the intended Replier. Since we don't want KBUS itself to block on + * (trying to) SEND a message to someone not expecting it, I don't think + * there are any other occasions when it is useful. + * + * 'from' is the id of the recipient who has gone away, not received the + * message, or whatever. + * + * 'to' is the 'from' for the message we're bouncing (or whatever). This + * needs to be local (it cannot be on another network), so we don't specify + * the network id. + * + * 'in_reply_to' should be the message id of that same message. + * + * Note that the message is essentially a Reply, so it only goes to the + * original Sender. + * + * Doesn't return anything since I can't think of anything useful to do if it + * goes wrong. + */ +static void kbus_push_synthetic_message(struct kbus_dev *dev, + uint32_t from, + uint32_t to, + struct kbus_msg_id in_reply_to, + char *name) +{ + struct kbus_private_data *priv = NULL; + struct kbus_msg *new_msg; + + /* Who *was* the original message to? */ + priv = kbus_find_open_ksock(dev, to); + if (!priv) { + printk(KERN_ERR + "kbus: %u pid %u [%s] Cannot send synthetic reply to %u," + " as they are gone\n", dev->index, current->pid, + current->comm, to); + return; + } + + kbus_maybe_dbg(priv->dev, "kbus: %u Pushing synthetic message '%s'" + " onto queue for %u\n", dev->index, name, to); + + /* + * Note that we do not check if the destination queue is full + * - we're going to trust that the "keep enough room in the + * message queue for a reply to each request" mechanism does + * it's job properly. + */ + + new_msg = kbus_build_kbus_message(dev, name, from, to, in_reply_to); + if (!new_msg) + return; + + (void)kbus_push_message(priv, new_msg, NULL, false); + /* ignore retval; we can't do anything useful if this goes wrong */ + + /* kbus_push_message takes a copy of our message */ + kbus_free_message(new_msg); +} + +/* + * Add the data part to a bind/unbind synthetic message. + * + * 'is_bind' is true if this was a "bind" event, false if it was an "unbind". + * + * 'name' is the message name (or wildcard) that was bound (or unbound) to. + * + * Returns 0 if all goes well, or a negative value if something goes wrong. + */ +static int kbus_add_bind_message_data(struct kbus_private_data *priv, + struct kbus_msg *new_msg, + uint32_t is_bind, + uint32_t name_len, char *name) +{ + struct kbus_replier_bind_event_data *data; + struct kbus_data_ptr *wrapped_data; + uint32_t padded_name_len = KBUS_PADDED_NAME_LEN(name_len); + uint32_t data_len = sizeof(*data) + padded_name_len; + uint32_t rest_len = padded_name_len / 4; + char *name_p; + + unsigned long *parts; + unsigned *lengths; + + data = kmalloc(data_len, GFP_KERNEL); + if (!data) { + kbus_free_message(new_msg); + return -ENOMEM; + } + + name_p = (char *)&data->rest[0]; + + data->is_bind = is_bind; + data->binder = priv->id; + data->name_len = name_len; + + data->rest[rest_len - 1] = 0; /* terminating with enough '\0' */ + strncpy(name_p, name, name_len); + + /* + * And that data, unfortunately for our simple mindedness, + * needs wrapping up in a reference count... + * + * Note/remember that we are happy for the reference counting + * wrapper to "own" our data, and free it when the it is done + * with it. + * + * I'm going to assert that we have less than a PAGE length + * of data, so we can simply do: + */ + parts = kmalloc(sizeof(*parts), GFP_KERNEL); + if (!parts) { + kfree(data); + return -ENOMEM; + } + lengths = kmalloc(sizeof(*lengths), GFP_KERNEL); + if (!lengths) { + kfree(parts); + kfree(data); + return -ENOMEM; + } + lengths[0] = data_len; + parts[0] = (unsigned long)data; + wrapped_data = + kbus_wrap_data_in_ref(false, 1, parts, lengths, data_len); + if (!wrapped_data) { + kfree(lengths); + kfree(parts); + kfree(data); + return -ENOMEM; + } + + new_msg->data_len = data_len; + new_msg->data_ref = wrapped_data; + return 0; +} + +/* + * Create a new Replier Bind Event synthetic message. + * + * The initial design of things didn't really expect us to be + * generating messages with actual data inside the kernel module, + * so it's all a little bit more complicated than it might otherwise + * be, and there's some playing with things directly that might best + * be done otherwise (notably, sorting out the wrapping up of the + * data in a reference count). I think that's excusable given this + * should be the only sort of message we ever generate with actual + * data (or so I believe). + * + * Returns the new message, or NULL. + */ +static struct kbus_msg +*kbus_new_synthetic_bind_message(struct kbus_private_data *priv, + uint32_t is_bind, + uint32_t name_len, char *name) +{ + ssize_t retval = 0; + struct kbus_msg *new_msg; + struct kbus_msg_id in_reply_to = { 0, 0 }; /* no-one */ + + kbus_maybe_dbg(priv->dev, + "kbus: %u Creating synthetic bind message for '%s'" + " (%s)\n", priv->dev->index, name, + is_bind ? "bind" : "unbind"); + + new_msg = kbus_build_kbus_message(priv->dev, + KBUS_MSG_NAME_REPLIER_BIND_EVENT, + 0, 0, in_reply_to); + if (!new_msg) + return NULL; + + /* + * What happens if any one of the listeners can't receive the message + * because they don't have room in their queues? + * + * If we flag the message as ALL_OR_FAIL, then if we can't deliver + * to all of the listeners who care, we will get -EBUSY returned to + * us, which we shall then return as -EAGAIN (people expect to check + * for -EAGAIN to find out if they should, well, try again). + * + * In this scenario, the user needs to catch a "bind"/"unbind" return + * of -EAGAIN and realise that it needs to try again. + */ + new_msg->flags |= KBUS_BIT_ALL_OR_FAIL; + + /* + * That gave us the basis of the message, but now we need to add in + * its meaning. + */ + retval = kbus_add_bind_message_data(priv, new_msg, is_bind, + name_len, name); + if (retval < 0) { + kbus_free_message(new_msg); + return NULL; + } + + return new_msg; +} + +/* + * Generate a bind/unbind synthetic message, and broadcast it. + * + * This is for use when we have been asked to announce when a Replier binds or + * unbinds. + * + * 'priv' is the sender - the entity that is doing the actual bind/unbind. + * + * 'is_bind' is true if this was a "bind" event, false if it was an "unbind". + * + * 'name' is the message name (or wildcard) that was bound (or unbound) to. + * + * Returns 0 if all goes well, or a negative value if something goes wrong, + * notably -EAGAIN if we couldn't send the message to ALL the Listeners who + * have bound to receive it. + */ +static int kbus_push_synthetic_bind_message(struct kbus_private_data *priv, + uint32_t is_bind, + uint32_t name_len, char *name) +{ + + ssize_t retval = 0; + struct kbus_msg *new_msg; + + kbus_maybe_dbg(priv->dev, + "kbus: %u Pushing synthetic bind message for '%s'" + " (%s) onto queue\n", priv->dev->index, name, + is_bind ? "bind" : "unbind"); + + new_msg = + kbus_new_synthetic_bind_message(priv, is_bind, name_len, name); + if (new_msg == NULL) + return -ENOMEM; + + kbus_maybe_report_message(priv->dev, KERN_DEBUG, new_msg); + kbus_maybe_dbg(priv->dev, + "kbus: Writing synthetic message to " + "recipients\n"); + + retval = kbus_write_to_recipients(priv, priv->dev, new_msg); + /* + * kbus_push_message takes a copy of our message data, so we + * must remember to free ours. Since we've made sure that it + * looks just like a user-generated message (i.e., the name + * can be freed as well as the data), this is fairly simple. + */ + kbus_free_message(new_msg); + + /* + * Because we used ALL_OR_FAIL, we will get -EBUSY back if we FAIL, + * but we want to tell the user -EAGAIN, since they *should* try + * again later. + */ + if (retval == -EBUSY) + retval = -EAGAIN; + + return retval; +} + +/* + * Pop the next message off our queue. + * + * Returns a pointer to the message, or NULL if there is no next message. + */ +static struct kbus_msg *kbus_pop_message(struct kbus_private_data *priv) +{ + struct list_head *queue = &priv->message_queue; + struct kbus_message_queue_item *item; + struct kbus_msg *msg = NULL; + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u Popping message from queue\n", + priv->dev->index, priv->id); + + if (list_empty(queue)) + return NULL; + + /* Retrieve the next message */ + item = list_first_entry(queue, struct kbus_message_queue_item, list); + + /* And straightway remove it from the list */ + list_del(&item->list); + + priv->message_count--; + + msg = item->msg; + kfree(item); + + /* If doing that made us go from no-room to some-room, wake up */ + if (priv->message_count == (priv->max_messages - 1)) + wake_up_interruptible(&priv->dev->write_wait); + + kbus_maybe_report_message(priv->dev, KERN_DEBUG, msg); + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Leaving %d message%s in queue\n", + priv->dev->index, priv->id, priv->message_count, + priv->message_count == 1 ? "" : "s"); + + return msg; +} + +/* + * Empty a message queue. Send synthetic messages for any outstanding + * request messages that are now not going to be delivered/replied to. + */ +static void kbus_empty_message_queue(struct kbus_private_data *priv) +{ + struct list_head *queue = &priv->message_queue; + struct kbus_message_queue_item *ptr; + struct kbus_message_queue_item *next; + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u Emptying message queue\n", + priv->dev->index, priv->id); + + list_for_each_entry_safe(ptr, next, queue, list) { + struct kbus_msg *msg = ptr->msg; + int is_OUR_request = (KBUS_BIT_WANT_YOU_TO_REPLY & msg->flags); + + kbus_maybe_report_message(priv->dev, KERN_DEBUG, msg); + + /* + * If it wanted a reply (from us). let the sender know it's + * going away (but take care not to send a message to + * ourselves, by accident!) + */ + if (is_OUR_request && msg->to != priv->id) + kbus_push_synthetic_message(priv->dev, priv->id, + msg->from, msg->id, + KBUS_MSG_NAME_REPLIER_GONEAWAY); + + /* Remove it from the list */ + list_del(&ptr->list); + /* And forget all about it... */ + kbus_free_message(ptr->msg); + + priv->message_count--; + } + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Leaving %d message%s in queue\n", + priv->dev->index, priv->id, priv->message_count, + priv->message_count == 1 ? "" : "s"); +} + +/* + * Add a message to the list of messages read by the replier, but still needing + * a reply. + */ +static int kbus_reply_needed(struct kbus_private_data *priv, + struct kbus_msg *msg) +{ + struct list_head *queue = &priv->replies_unsent; + struct kbus_unreplied_item *item; + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Adding message %u:%u to unsent " + "replies list\n", + priv->dev->index, priv->id, msg->id.network_id, + msg->id.serial_num); + + item = kmalloc(sizeof(*item), GFP_KERNEL); + if (!item) { + printk(KERN_ERR "kbus: Cannot kmalloc reply-needed item\n"); + return -ENOMEM; + } + + item->id = msg->id; + item->from = msg->from; + item->name_len = msg->name_len; + /* + * It seems sensible to use a reference to the name. I believe + * we are safe to do this because we have the message "in hand". + */ + item->name_ref = kbus_raise_name_ref(msg->name_ref); + + list_add(&item->list, queue); + + priv->num_replies_unsent++; + + if (priv->num_replies_unsent > priv->max_replies_unsent) + priv->max_replies_unsent = priv->num_replies_unsent; + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Leaving %d message%s unreplied-to\n", + priv->dev->index, priv->id, priv->num_replies_unsent, + priv->num_replies_unsent == 1 ? "" : "s"); + + return 0; +} + +/* + * Remove a message from the list of (read) messages needing a reply + * + * Returns 0 on success, -1 if it could not find the message + */ +static int kbus_reply_now_sent(struct kbus_private_data *priv, + struct kbus_msg_id *msg_id) +{ + struct list_head *queue = &priv->replies_unsent; + struct kbus_unreplied_item *ptr; + struct kbus_unreplied_item *next; + + list_for_each_entry_safe(ptr, next, queue, list) { + if (!kbus_same_message_id(&ptr->id, + msg_id->network_id, + msg_id->serial_num)) + continue; + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Reply to %u:%u %.*s now sent\n", + priv->dev->index, priv->id, msg_id->network_id, + msg_id->serial_num, ptr->name_len, ptr->name_ref->name); + + /* Remove it from the list */ + list_del(&ptr->list); + /* And forget all about it... */ + kbus_lower_name_ref(ptr->name_ref); + kfree(ptr); + + priv->num_replies_unsent--; + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Leaving %d message%s unreplied-to\n", + priv->dev->index, priv->id, priv->num_replies_unsent, + priv->num_replies_unsent == 1 ? "" : "s"); + + return 0; + } + + printk(KERN_ERR "kbus: %u/%u Could not find message %u:%u in unsent " + "replies list\n", + priv->dev->index, priv->id, msg_id->network_id, + msg_id->serial_num); + return -1; +} + +/* + * Empty our "replies unsent" queue. Send synthetic messages for any + * request messages that are now not going to be replied to. + */ +static void kbus_empty_replies_unsent(struct kbus_private_data *priv) +{ + struct list_head *queue = &priv->replies_unsent; + struct kbus_unreplied_item *ptr; + struct kbus_unreplied_item *next; + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Emptying unreplied messages list\n", + priv->dev->index, priv->id); + + list_for_each_entry_safe(ptr, next, queue, list) { + + kbus_push_synthetic_message(priv->dev, priv->id, + ptr->from, ptr->id, + KBUS_MSG_NAME_REPLIER_IGNORED); + + /* Remove it from the list */ + list_del(&ptr->list); + /* And forget all about it... */ + kbus_lower_name_ref(ptr->name_ref); + kfree(ptr); + + priv->num_replies_unsent--; + } + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Leaving %d message%s unreplied-to\n", + priv->dev->index, priv->id, priv->num_replies_unsent, + priv->num_replies_unsent == 1 ? "" : "s"); +} + +/* + * Find out who, if anyone, is bound as a replier to the given message name. + * + * Returns 1 if we found a replier, 0 if we did not (but all went well), and + * a negative value if something went wrong. + */ +static int kbus_find_replier(struct kbus_dev *dev, + struct kbus_private_data **bound_to, + uint32_t name_len, char *name) +{ + struct kbus_message_binding *ptr; + struct kbus_message_binding *next; + + /* We don't want anyone writing to the list whilst we do this */ + list_for_each_entry_safe(ptr, next, &dev->bound_message_list, list) { + /* + * We are only interested in a replier binding to the name. + * We *could* check for the name and then check for + * reply-ness - if we found a name match that was *not* a + * replyer, then we'd have finished. However, checking the + * name is expensive, and I rather assume that a caller is + * only checking if they expect a positive result, so it's + * simpler to do a lazier check. + */ + if (!ptr->is_replier || ptr->name_len != name_len || + strncmp(name, ptr->name, name_len)) + continue; + + kbus_maybe_dbg(dev, "kbus: %u '%.*s' has replier %u\n", + dev->index, ptr->name_len, ptr->name, + ptr->bound_to_id); + *bound_to = ptr->bound_to; + return 1; + } + return 0; +} + +/* + * Find out who, if anyone, is bound as listener/replier to this message name. + * + * 'listeners' is an array of (pointers to) listener bindings. It may be NULL + * (if there are no listeners or if there was an error). It is up to the caller + * to free it. It does not include (pointers to) any replier binding. + * + * If there is also a replier for this message, then 'replier' will be (a + * pointer to) its binding, otherwise it will be NULL. The replier will not be + * in the 'listeners' array, so the caller must check both. + * + * Note that a particular listener may be present more than once, if that + * particular listener has bound to the message more than once (but no + * *binding* will be represented more than once). + * + * Returns the number of listeners found (i.e., the length of the array), or a + * negative value if something went wrong. This is a bit clumsy, because the + * caller needs to check the return value *and* the 'replier' value, but there + * is only one caller, so... + */ +static int kbus_find_listeners(struct kbus_dev *dev, + struct kbus_message_binding **listeners[], + struct kbus_message_binding **replier, + uint32_t name_len, char *name) +{ + int count = 0; + int array_size = KBUS_INIT_LISTENER_ARRAY_SIZE; + struct kbus_message_binding *ptr; + struct kbus_message_binding *next; + + enum kbus_replier_type replier_type = UNSET; + enum kbus_replier_type new_replier_type = UNSET; + + kbus_maybe_dbg(dev, + "kbus: Looking for listeners/repliers for '%.*s'\n", + name_len, name); + + *listeners = + kmalloc(array_size * sizeof(struct kbus_message_binding *), + GFP_KERNEL); + if (!(*listeners)) + return -ENOMEM; + + *replier = NULL; + + list_for_each_entry_safe(ptr, next, &dev->bound_message_list, list) { + + if (!kbus_message_name_matches(name, name_len, ptr->name)) + continue; + + kbus_maybe_dbg(dev, "kbus: Name '%.*s' matches " + "'%s' for %s %u\n", + name_len, name, ptr->name, + ptr->is_replier ? "replier" : "listener", + ptr->bound_to_id); + + if (ptr->is_replier) { + /* It *may* be the replier for this message */ + size_t last_char = strlen(ptr->name) - 1; + if (ptr->name[last_char] == '*') + new_replier_type = WILD_STAR; + else if (ptr->name[last_char] == '%') + new_replier_type = WILD_PERCENT; + else + new_replier_type = SPECIFIC; + + kbus_maybe_dbg(dev, + "kbus: ..previous replier was %u " + "(%s), looking at %u (%s)\n", + ((*replier) == NULL ? 0 : + (*replier)->bound_to_id), + kbus_replier_type_name(replier_type), + ptr->bound_to_id, + kbus_replier_type_name(new_replier_type)); + + /* + * If this is the first replier, just remember + * it. Otherwise, if it's more specific than + * our previous replier, remember it instead. + */ + if (*replier == NULL || + new_replier_type > replier_type) { + + kbus_conditional_dbg(*replier, dev, + "kbus: ..going with " + "replier %u (%s)\n", ptr->bound_to_id, + kbus_replier_type_name( + new_replier_type)); + + *replier = ptr; + replier_type = new_replier_type; + } else { + kbus_conditional_dbg(*replier, dev, + "kbus: ..keeping replier %u (%s)\n", + (*replier)->bound_to_id, + kbus_replier_type_name(replier_type)); + } + } else { + /* It is a listener */ + if (count == array_size) { + uint32_t new_size = kbus_next_size(array_size); + + kbus_maybe_dbg(dev, "kbus: XXX listener " + "array size %d -> %d\n", + array_size, new_size); + + array_size = new_size; + *listeners = krealloc(*listeners, + sizeof(**listeners) * array_size, + GFP_KERNEL); + if (!(*listeners)) + return -EFAULT; + } + (*listeners)[count++] = ptr; + } + } + + kbus_maybe_dbg(dev, "kbus: Found %d listener%s%s for '%.*s'\n", + count, (count == 1 ? "" : "s"), + (*replier == NULL ? "" : " and a replier"), + name_len, name); + + return count; +} + +/* + * Add a new binding. + * + * Doesn't allow more than one replier to be bound for a message name. + * + * NB: If it succeeds, then it wants to keep hold of 'name', so don't + * free it... + * + * Returns 0 if all went well, a negative value if it did not. Specifically, + * -EADDRINUSE if an attempt was made to bind as a replier to a message name + * that already has a replier bound. + */ +static int kbus_remember_binding(struct kbus_dev *dev, + struct kbus_private_data *priv, + uint32_t replier, + uint32_t name_len, char *name) +{ + int retval = 0; + struct kbus_message_binding *new; + + /* If we want a replier, and there already is one, we lose */ + if (replier) { + struct kbus_private_data *reply_to; + retval = kbus_find_replier(dev, &reply_to, name_len, name); + /* + * "Address in use" isn't quite right, but lets the caller + * have some hope of telling what went wrong, and this is a + * useful case to distinguish. + */ + if (retval == 1) { + kbus_maybe_dbg(dev, + "kbus: %u/%u CANNOT BIND '%.*s' as " + "replier, already bound\n", + dev->index, priv->id, + name_len, name); + return -EADDRINUSE; + } + } + + new = kmalloc(sizeof(*new), GFP_KERNEL); + if (!new) + return -ENOMEM; + + new->bound_to = priv; + new->bound_to_id = priv->id; /* Useful shorthand? */ + new->is_replier = replier; + new->name_len = name_len; + new->name = name; + + if (replier && dev->report_replier_binds) { + /* + * We've been asked to announce when a Replier binds. + * If we can't tell all the Listeners who care, we want + * to give up, rather than tell some of them, and then + * bind anyway. + */ + retval = kbus_push_synthetic_bind_message(priv, true, + name_len, name); + if (retval != 0) { /* Hopefully, just -EBUSY */ + kfree(new); + return retval; + } + } + + list_add(&new->list, &dev->bound_message_list); + return 0; +} + +/* + * Find a particular binding. + * + * Return a pointer to the binding, or NULL if it was not found. + */ +static struct kbus_message_binding +*kbus_find_binding(struct kbus_dev *dev, + struct kbus_private_data *priv, + uint32_t replier, uint32_t name_len, char *name) +{ + struct kbus_message_binding *ptr; + struct kbus_message_binding *next; + + list_for_each_entry_safe(ptr, next, &dev->bound_message_list, list) { + if (priv != ptr->bound_to) + continue; + if (replier != ptr->is_replier) + continue; + if (name_len != ptr->name_len) + continue; + if (strncmp(name, ptr->name, name_len)) + continue; + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u Found %c '%.*s'\n", + dev->index, priv->id, + (ptr->is_replier ? 'R' : 'L'), + ptr->name_len, ptr->name); + return ptr; + } + return NULL; +} + +/* + * Forget any messages (in our queue) that were only in the queue because of + * the binding we're removing. + * + * If the message was a request (needing a reply) generate an appropriate + * synthetic message. + */ +static void kbus_forget_matching_messages(struct kbus_private_data *priv, + struct kbus_message_binding *binding) +{ + struct list_head *queue = &priv->message_queue; + struct kbus_message_queue_item *ptr; + struct kbus_message_queue_item *next; + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Forgetting matching messages\n", + priv->dev->index, priv->id); + + list_for_each_entry_safe(ptr, next, queue, list) { + struct kbus_msg *msg = ptr->msg; + int is_OUR_request = (KBUS_BIT_WANT_YOU_TO_REPLY & msg->flags); + + /* + * If this message was not added to the queue because of this + * binding, then we are not interested in it... + */ + if (ptr->binding != binding) + continue; + + kbus_maybe_dbg(priv->dev, + "kbus: Deleting message from queue\n"); + kbus_maybe_report_message(priv->dev, KERN_DEBUG, msg); + + /* + * If it wanted a reply (from us). let the sender know it's + * going away (but take care not to send a message to + * ourselves, by accident!) + */ + if (is_OUR_request && msg->to != priv->id) { + + kbus_maybe_dbg(priv->dev, "kbus: >>> is_OUR_request," + " sending fake reply\n"); + kbus_maybe_report_message(priv->dev, KERN_DEBUG, msg); + kbus_push_synthetic_message(priv->dev, priv->id, + msg->from, msg->id, + KBUS_MSG_NAME_REPLIER_UNBOUND); + } + + /* Remove it from the list */ + list_del(&ptr->list); + /* And forget all about it... */ + kbus_free_message(ptr->msg); + + priv->message_count--; + + /* If that made us go from no-room to some-room, wake up */ + if (priv->message_count == (priv->max_messages - 1)) + wake_up_interruptible(&priv->dev->write_wait); + } + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Leaving %d message%s in queue\n", + priv->dev->index, priv->id, priv->message_count, + priv->message_count == 1 ? "" : "s"); +} + +/* + * Remove an existing binding. + * + * Returns 0 if all went well, a negative value if it did not. + */ +static int kbus_forget_binding(struct kbus_dev *dev, + struct kbus_private_data *priv, + uint32_t replier, uint32_t name_len, char *name) +{ + struct kbus_message_binding *binding; + + binding = kbus_find_binding(dev, priv, replier, name_len, name); + if (binding == NULL) { + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Could not find/unbind " + "%u %c '%.*s'\n", + dev->index, priv->id, priv->id, + (replier ? 'R' : 'L'), name_len, name); + return -EINVAL; + } + + if (replier && dev->report_replier_binds) { + + /* + * We want to send a message indicating that we've unbound + * the Replier for this message. + * + * If we can't tell all the Listeners who're listening for this + * message, we want to give up, rather then tell some of them, + * and then unbind anyway. + */ + int retval = kbus_push_synthetic_bind_message(priv, false, + name_len, name); + if (retval != 0) /* Hopefully, just -EBUSY */ + return retval; + /* + * Note that if we were ourselves listening for replier bind + * events, then we will ourselves get the message announcing + * we're about to unbind. + */ + } + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u Unbound %u %c '%.*s'\n", + dev->index, priv->id, + binding->bound_to_id, + (binding->is_replier ? 'R' : 'L'), + binding->name_len, binding->name); + + /* And forget any messages we now shouldn't receive */ + kbus_forget_matching_messages(priv, binding); + + /* + * Maybe including any set-aside Replier Unbind Events... + */ + if (!strncmp(KBUS_MSG_NAME_REPLIER_BIND_EVENT, binding->name, + binding->name_len)) + kbus_forget_unbound_unsent_unbind_msgs(priv, binding); + + /* + * We carefully don't try to do anything about requests that + * have already been read - the fact that the user has unbound + * from receiving new messages with this name doesn't imply + * anything about whether they're going to reply to requests + * (with that name) which they've already read. + */ + + /* And remove the binding once that has been done. */ + list_del(&binding->list); + kfree(binding->name); + kfree(binding); + return 0; +} + +/* + * Add a (copy of a) message to the "unsent Replier Unbind Event" list + * + * 'priv' is who we are trying to send to, 'msg' is the message we were + * trying to send. + * + * Returns 0 if all went well, a negative value if it did not. + */ +static int kbus_remember_unsent_unbind_event(struct kbus_dev *dev, + struct kbus_private_data *priv, + struct kbus_msg *msg, + struct kbus_message_binding + *binding) +{ + struct kbus_unsent_message_item *new; + struct kbus_msg *new_msg = NULL; + + kbus_maybe_dbg(priv->dev, + "kbus: %u Remembering unsent unbind event " + "%u '%.*s' to %u\n", + dev->index, dev->unsent_unbind_msg_count, msg->name_len, + msg->name_ref->name, priv->id); + + new = kmalloc(sizeof(*new), GFP_KERNEL); + if (!new) + return -ENOMEM; + + new_msg = kbus_copy_message(msg); + if (!new_msg) { + kfree(new); + return -EFAULT; + } + + new->send_to = priv; + new->send_to_id = priv->id; /* Useful shorthand? */ + new->msg = new_msg; + new->binding = binding; + + /* + * The order should be the same as a normal message queue, + * so add to the end... + */ + list_add_tail(&new->list, &dev->unsent_unbind_msg_list); + dev->unsent_unbind_msg_count++; + return 0; +} + +/* + * Return true if this listener already has a "gone tragic" message. + * + * Look at the end of the unsent Replier Unbind Event message list, to see + * if the given listener already has a "gone tragic" message (since if it + * does, we will not want to add another). + */ +static int kbus_listener_already_got_tragic_msg(struct kbus_dev *dev, + struct kbus_private_data + *listener) +{ + struct kbus_unsent_message_item *ptr; + struct kbus_unsent_message_item *next; + + kbus_maybe_dbg(dev, + "kbus: %u Checking for 'gone tragic' event for %u\n", + dev->index, listener->id); + + list_for_each_entry_safe_reverse(ptr, next, + &dev->unsent_unbind_msg_list, list) { + + if (kbus_message_name_matches( + ptr->msg->name_ref->name, + ptr->msg->name_len, + KBUS_MSG_NAME_REPLIER_BIND_EVENT)) + /* + * If we get a Replier Bind Event, then we're past all + * the "tragic world" messages + */ + break; + if (ptr->send_to_id == listener->id) { + kbus_maybe_dbg(dev, "kbus: %u Found\n", dev->index); + return true; + } + } + + kbus_maybe_dbg(dev, "kbus: %u Not found\n", dev->index); + return false; +} + +/* + * Report a Replier Bind Event for unbinding from the given message name, + * in such a way that we do not lose the message even if we can't send it + * right away. + */ +static void kbus_safe_report_unbinding(struct kbus_private_data *priv, + uint32_t name_len, char *name) +{ + /* 1. Generate a new unbinding event message + * 2. Try sending it to everyone who cares + * 3. If that failed, then find out who *does* care + * 4. Is there room for that many messages on the set-aside list? + * 5. If there is, add (a copy of) the message for each + * 6. If there is not, set the "tragic" flag, and add (a copy of) + * the "world gone tragic" message for each + * 7. If we've added something to the set-aside list, then set + * the "maybe got something on the set-aside list" flag for + * each recipient. */ + + struct kbus_msg *msg; + struct kbus_message_binding **listeners = NULL; + struct kbus_message_binding *replier = NULL; + int retval = 0; + int num_listeners; + int ii; + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Safe report unbinding of '%.*s'\n", + priv->dev->index, priv->id, name_len, name); + + /* Generate the message we'd *like* to send */ + msg = kbus_new_synthetic_bind_message(priv, false, name_len, name); + if (msg == NULL) + return; /* There is nothing sensible to do here */ + + /* If we're lucky, we can just send it */ + retval = kbus_write_to_recipients(priv, priv->dev, msg); + if (retval != -EBUSY) + goto done_sending; + + /* + * So at least one of the people we were trying to send to was not able + * to take the message, presumably because their message queue is full. + * Thus we need to put aside one copy of the message for each + * recipient, to be delivered when it *can* be received. + * + * So before we do anything else, we need to know who those recipients + * are. + */ + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Need to add messages to set-aside list\n", + priv->dev->index, priv->id); + + /* + * We're expecting some listeners, but no replier. + * Since this is a duplicate of what we did in kbus_write_to_recipients, + * and since our ksock is locked whilst we're working, we can assume + * that we should get the same result. For the sake of completeness, + * check the error return anyway, but I'm not going to worry about + * whether we suddenly have a replier popping up unexpectedly... + */ + num_listeners = kbus_find_listeners(priv->dev, &listeners, &replier, + msg->name_len, msg->name_ref->name); + if (num_listeners < 0) { + kbus_maybe_dbg(priv->dev, + "kbus: Error %d finding listeners\n", + num_listeners); + retval = num_listeners; + goto done_sending; + } + + if (priv->dev->unsent_unbind_is_tragic || + (num_listeners + priv->dev->unsent_unbind_msg_count > + CONFIG_KBUS_MAX_UNSENT_UNBIND_MESSAGES)) { + struct kbus_msg_id in_reply_to = { 0, 0 }; /* no-one */ + /* + * Either the list had already gone tragic, or we've + * filled it up with "normal" unbind event messages + */ + priv->dev->unsent_unbind_is_tragic = true; + + /* In which case we need a different message */ + kbus_free_message(msg); + msg = kbus_build_kbus_message(priv->dev, + KBUS_MSG_NAME_UNBIND_EVENTS_LOST, + 0, 0, in_reply_to); + if (msg == NULL) + goto done_sending; + + for (ii = 0; ii < num_listeners; ii++) { + /* + * We only want to add a "gone tragic" message if the + * recipient does not already have such a message + * stacked... + */ + if (kbus_listener_already_got_tragic_msg(priv->dev, + listeners[ii]->bound_to)) + continue; + retval = kbus_remember_unsent_unbind_event(priv->dev, + listeners[ii]->bound_to, + msg, listeners[ii]); + /* And remember that we've got something on the + * set-aside list */ + listeners[ii]->bound_to->maybe_got_unsent_unbind_msgs = + true; + if (retval) + break; /* No good choice here */ + } + } else { + /* There's room to add these messages as-is */ + for (ii = 0; ii < num_listeners; ii++) { + retval = kbus_remember_unsent_unbind_event(priv->dev, + listeners[ii]->bound_to, + msg, listeners[ii]); + /* And remember that we've got something on the + * set-aside list */ + listeners[ii]->bound_to->maybe_got_unsent_unbind_msgs = + true; + if (retval) + break; /* No good choice here */ + } + } + +done_sending: + kfree(listeners); + /* Don't forget to free our copy of the message */ + if (msg) + kbus_free_message(msg); + /* We aren't returning any status code. Oh well. */ +} + +/* + * Return how many messages we have in the unsent Replier Unbind Event list. + */ +static uint32_t kbus_count_unsent_unbind_msgs(struct kbus_private_data *priv) +{ + struct kbus_dev *dev = priv->dev; + + struct kbus_unsent_message_item *ptr; + struct kbus_unsent_message_item *next; + + uint32_t count = 0; + + kbus_maybe_dbg(dev, "kbus: %u/%u Counting unsent unbind messages\n", + dev->index, priv->id); + + list_for_each_entry_safe(ptr, next, &dev->unsent_unbind_msg_list, + list) { + if (ptr->send_to_id == priv->id) + count++; + } + return count; +} + +/* + * Maybe move an unsent Replier Unbind Event message to the main message list. + * + * Check if we have an unsent event on the set-aside list. If we do, move the + * first one across to our normal message queue. + * + * Returns 0 if all goes well, or a negative value if something went wrong. + */ +static int kbus_maybe_move_unsent_unbind_msg(struct kbus_private_data *priv) +{ + struct kbus_dev *dev = priv->dev; + + struct kbus_unsent_message_item *ptr; + struct kbus_unsent_message_item *next; + + kbus_maybe_dbg(dev, + "kbus: %u/%u Looking for an unsent unbind message\n", + dev->index, priv->id); + + list_for_each_entry_safe(ptr, next, &dev->unsent_unbind_msg_list, + list) { + int retval; + + if (ptr->send_to_id != priv->id) + continue; + + kbus_maybe_report_message(priv->dev, KERN_DEBUG, ptr->msg); + /* + * Move the message into our normal message queue. + * + * We *must* use kbus_push_message() to do this, as + * we wish to keep our promise that this shall be the + * only way of adding a message to the queue. + */ + retval = kbus_push_message(priv, ptr->msg, ptr->binding, false); + if (retval) + return retval; /* What else can we do? */ + + /* Remove it from the list */ + list_del(&ptr->list); + /* Mustn't forget to free *our* copy of the message */ + kbus_free_message(ptr->msg); + kfree(ptr); + dev->unsent_unbind_msg_count--; + goto check_tragic; + } + + /* + * Since we didn't find anything, we can safely unset the flag that + * says there might be something to find... + */ + priv->maybe_got_unsent_unbind_msgs = false; + +check_tragic: + /* + * And if we've succeeded in emptying the list, we can unset the + * "gone tragic" flag for it, too, if it was set. + */ + if (list_empty(&dev->unsent_unbind_msg_list)) + dev->unsent_unbind_is_tragic = false; + return 0; +} + +/* + * Forget any outstanding unsent Replier Unbind Event messages for this binding. + * + * Called from kbus_release. + */ +static void kbus_forget_unbound_unsent_unbind_msgs(struct kbus_private_data + *priv, + struct kbus_message_binding + *binding) +{ + struct kbus_dev *dev = priv->dev; + + struct kbus_unsent_message_item *ptr; + struct kbus_unsent_message_item *next; + + uint32_t count = 0; + + kbus_maybe_dbg(dev, + "kbus: %u/%u Forgetting unsent unbind messages for " + "this binding\n", + dev->index, priv->id); + + list_for_each_entry_safe(ptr, next, &dev->unsent_unbind_msg_list, + list) { + if (ptr->binding == binding) { + /* Remove it from the list */ + list_del(&ptr->list); + /* And forget all about it... */ + kbus_free_message(ptr->msg); + kfree(ptr); + dev->unsent_unbind_msg_count--; + count++; + } + } + kbus_maybe_dbg(dev, "kbus: %u/%u Forgot %u unsent unbind messages\n", + dev->index, priv->id, count); + /* + * And if we've succeeded in emptying the list, we can unset the + * "gone tragic" flag for it, too, if it was set. + */ + if (list_empty(&dev->unsent_unbind_msg_list)) + dev->unsent_unbind_is_tragic = false; +} + +/* + * Forget any outstanding unsent Replier Unbind Event messages for this Replier. + * + * Called from kbus_release. + */ +static void kbus_forget_my_unsent_unbind_msgs(struct kbus_private_data *priv) +{ + struct kbus_dev *dev = priv->dev; + + struct kbus_unsent_message_item *ptr; + struct kbus_unsent_message_item *next; + + uint32_t count = 0; + + kbus_maybe_dbg(dev, + "kbus: %u/%u Forgetting my unsent unbind messages\n", + dev->index, priv->id); + + list_for_each_entry_safe(ptr, next, &dev->unsent_unbind_msg_list, + list) { + if (ptr->send_to_id == priv->id) { + /* Remove it from the list */ + list_del(&ptr->list); + /* And forget all about it... */ + kbus_free_message(ptr->msg); + kfree(ptr); + dev->unsent_unbind_msg_count--; + count++; + } + } + kbus_maybe_dbg(dev, "kbus: %u/%u Forgot %u unsent unbind messages\n", + dev->index, priv->id, count); + /* + * And if we've succeeded in emptying the list, we can unset the + * "gone tragic" flag for it, too, if it was set. + */ + if (list_empty(&dev->unsent_unbind_msg_list)) + dev->unsent_unbind_is_tragic = false; +} + +/* + * Forget any outstanding unsent Replier Unbind Event messages. + * + * Assumed to be called because the device is closing, and thus doesn't lock, + * or worry about lost messages. + */ +static void kbus_forget_unsent_unbind_msgs(struct kbus_dev *dev) +{ + struct kbus_unsent_message_item *ptr; + struct kbus_unsent_message_item *next; + + kbus_maybe_dbg(dev, + "kbus: %u Forgetting unsent unbind event messages\n", + dev->index); + + list_for_each_entry_safe(ptr, next, &dev->unsent_unbind_msg_list, + list) { + + if (!kbus_message_name_matches( + ptr->msg->name_ref->name, + ptr->msg->name_len, + KBUS_MSG_NAME_REPLIER_BIND_EVENT)) + kbus_maybe_report_message(dev, KERN_DEBUG, ptr->msg); + + /* Remove it from the list */ + list_del(&ptr->list); + /* And forget all about it... */ + kbus_free_message(ptr->msg); + kfree(ptr); + dev->unsent_unbind_msg_count--; + } +} + +/* + * Remove all bindings for a particular listener. + * + * Called from kbus_release, which will itself handle removing messages + * (that *were* bound) from the message queue. + */ +static void kbus_forget_my_bindings(struct kbus_private_data *priv) +{ + struct kbus_dev *dev = priv->dev; + uint32_t bound_to_id = priv->id; + + struct kbus_message_binding *ptr; + struct kbus_message_binding *next; + + kbus_maybe_dbg(dev, "kbus: %u/%u Forgetting my bindings\n", + dev->index, priv->id); + + list_for_each_entry_safe(ptr, next, &dev->bound_message_list, list) { + if (bound_to_id != ptr->bound_to_id) + continue; + + kbus_maybe_dbg(dev, "kbus: Unbound %u %c '%.*s'\n", + ptr->bound_to_id, (ptr->is_replier ? 'R' : 'L'), + ptr->name_len, ptr->name); + + if (ptr->is_replier && dev->report_replier_binds) + kbus_safe_report_unbinding(priv, ptr->name_len, + ptr->name); + + list_del(&ptr->list); + kfree(ptr->name); + kfree(ptr); + } +} + +/* + * Remove all bindings. + * + * Assumed to be called because the device is closing, and thus doesn't lock, + * nor does it worry about generating synthetic messages as requests are doomed + * not to get replies. + */ +static void kbus_forget_all_bindings(struct kbus_dev *dev) +{ + struct kbus_message_binding *ptr; + struct kbus_message_binding *next; + + kbus_maybe_dbg(dev, "kbus: %u Forgetting bindings\n", dev->index); + + list_for_each_entry_safe(ptr, next, &dev->bound_message_list, list) { + + kbus_maybe_dbg(dev, "kbus: Unbinding %u %c '%.*s'\n", + ptr->bound_to_id, + (ptr->is_replier ? 'R' : 'L'), + ptr->name_len, ptr->name); + + /* And we don't want anyone reading for this */ + list_del(&ptr->list); + kfree(ptr->name); + kfree(ptr); + } +} + +/* + * Add a new open file to our remembrances. + * + * Returns 0 if all went well, a negative value if it did not. + */ +static int kbus_remember_open_ksock(struct kbus_dev *dev, + struct kbus_private_data *priv) +{ + list_add(&priv->list, &dev->open_ksock_list); + + kbus_maybe_dbg(priv->dev, "kbus: Remembered 'open file' id %u\n", + priv->id); + return 0; +} + +/* + * Retrieve the pointer to an open file's data + * + * Return NULL if we can't find it. + */ +static struct kbus_private_data *kbus_find_open_ksock(struct kbus_dev *dev, + uint32_t id) +{ + struct kbus_private_data *ptr; + struct kbus_private_data *next; + + list_for_each_entry_safe(ptr, next, &dev->open_ksock_list, list) { + if (id == ptr->id) { + kbus_maybe_dbg(dev, "kbus: %u Found open Ksock %u\n", + dev->index, id); + return ptr; + } + } + kbus_maybe_dbg(dev, "kbus: %u Could not find open Ksock %u\n", + dev->index, id); + return NULL; +} + +/* + * Remove an open file remembrance. + * + * Returns 0 if all went well, -EINVAL if we couldn't find the open Ksock + */ +static int kbus_forget_open_ksock(struct kbus_dev *dev, uint32_t id) +{ + struct kbus_private_data *ptr; + struct kbus_private_data *next; + + /* We don't want anyone writing to the list whilst we do this */ + list_for_each_entry_safe(ptr, next, &dev->open_ksock_list, list) { + if (id != ptr->id) + continue; + + kbus_maybe_dbg(dev, "kbus: %u Forgetting open Ksock %u\n", + dev->index, id); + + /* So remove it from our list */ + list_del(&ptr->list); + /* But *we* mustn't free the actual datastructure! */ + return 0; + } + kbus_maybe_dbg(dev, "kbus: %u Could not forget open Ksock %u\n", + dev->index, id); + + return -EINVAL; +} + +/* + * Forget all our "open file" remembrances. + * + * Assumed to be called because the device is closing, and thus doesn't lock. + */ +static void kbus_forget_all_open_ksocks(struct kbus_dev *dev) +{ + struct kbus_private_data *ptr; + struct kbus_private_data *next; + + list_for_each_entry_safe(ptr, next, &dev->open_ksock_list, list) { + + kbus_maybe_dbg(dev, "kbus: %u Forgetting open Ksock %u\n", + dev->index, ptr->id); + + /* So remove it from our list */ + list_del(&ptr->list); + /* But *we* mustn't free the actual datastructure! */ + } +} + +static int kbus_open(struct inode *inode, struct file *filp) +{ + struct kbus_private_data *priv; + struct kbus_dev *dev; + + priv = kmalloc(sizeof(*priv), GFP_KERNEL); + if (!priv) + return -ENOMEM; + + /* + * Use the official magic to retrieve our actual device data + * so we can remember it for other file operations. + */ + dev = container_of(inode->i_cdev, struct kbus_dev, cdev); + + if (mutex_lock_interruptible(&dev->mux)) { + kfree(priv); + return -ERESTARTSYS; + } + + /* + * Our file descriptor id ("listener id") needs to be unique for this + * device, and thus we want to be carefully inside our lock. + * + * We shall (for now at least) ignore wrap-around - 32 bits is big + * enough that it shouldn't cause non-unique ids in our target + * applications. + * + * Listener id 0 is reserved, and we'll use that (on occasion) to mean + * kbus itself. + */ + if (dev->next_ksock_id == 0) + dev->next_ksock_id++; + + memset(priv, 0, sizeof(*priv)); + priv->dev = dev; + priv->id = dev->next_ksock_id++; + priv->pid = current->pid; + priv->max_messages = CONFIG_KBUS_DEF_MAX_MESSAGES; + priv->sending = false; + priv->num_replies_unsent = 0; + priv->max_replies_unsent = 0; + + if (kbus_init_msg_id_memory(priv)) { + kbus_empty_read_msg(priv); + kfree(priv); + return -EFAULT; + } + INIT_LIST_HEAD(&priv->message_queue); + INIT_LIST_HEAD(&priv->replies_unsent); + + init_waitqueue_head(&priv->read_wait); + + /* Note that we immediately have a space available for a message */ + wake_up_interruptible(&dev->write_wait); + + (void)kbus_remember_open_ksock(dev, priv); + + filp->private_data = priv; + + mutex_unlock(&dev->mux); + + kbus_maybe_dbg(dev, "kbus: %u/%u OPEN\n", dev->index, priv->id); + + return 0; +} + +static int kbus_release(struct inode *inode __always_unused, struct file *filp) +{ + int retval2 = 0; + struct kbus_private_data *priv = filp->private_data; + struct kbus_dev *dev = priv->dev; + + if (mutex_lock_interruptible(&dev->mux)) + return -ERESTARTSYS; + + kbus_maybe_dbg(dev, "kbus: %u/%u RELEASE\n", dev->index, priv->id); + + kbus_empty_read_msg(priv); + kbus_empty_write_msg(priv); + + kbus_empty_msg_id_memory(priv); + + kbus_empty_message_queue(priv); + kbus_forget_my_bindings(priv); + if (priv->maybe_got_unsent_unbind_msgs) + kbus_forget_my_unsent_unbind_msgs(priv); + kbus_empty_replies_unsent(priv); + retval2 = kbus_forget_open_ksock(dev, priv->id); + kfree(priv); + + mutex_unlock(&dev->mux); + + return retval2; +} + +/* + * Determine the private data for the given listener/replier id. + * + * Return NULL if we can't find it. + */ +static struct kbus_private_data +*kbus_find_private_data(struct kbus_private_data *our_priv, + struct kbus_dev *dev, uint32_t id) +{ + struct kbus_private_data *l_priv; + if (id == our_priv->id) { + /* Heh, it's us, we know who we are! */ + kbus_maybe_dbg(dev, "kbus: -- Id %u is us\n", id); + + l_priv = our_priv; + } else { + /* OK, look it up */ + kbus_maybe_dbg(dev, "kbus: -- Looking up id %u\n", id); + + l_priv = kbus_find_open_ksock(dev, id); + } + return l_priv; +} + +/* + * Determine if the specified recipient has room for a message in their queue + * + * - 'priv' is the recipient + * - 'what' is a string describing them (e.g., "sender", "replier"), just + * for use in debugging/grumbling + * - if 'is_reply' is true, then we're checking for a Reply message, + * which we already know is expected by the specified recipient. + */ +static int kbus_queue_is_full(struct kbus_private_data *priv, + char *what __maybe_unused, int is_reply) +{ + /* + * When figuring out how "full" the message queue is, we need + * to take account of the messages already in the queue (!), + * and also the replies that still need to be written to the + * queue. + * + * Of course, if we're checking because we want to send one + * of the Replies that we are keeping room for, we need to + * remember to account for that! + */ + int already_accounted_for = priv->message_count + + priv->outstanding_requests.count; + + if (is_reply) + already_accounted_for--; + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Message queue: count %d + " + "outstanding %d %s= %d, max %d\n", + priv->dev->index, priv->id, priv->message_count, + priv->outstanding_requests.count, + (is_reply ? "-1 " : ""), already_accounted_for, + priv->max_messages); + + if (already_accounted_for < priv->max_messages) { + return false; + } else { + kbus_maybe_dbg(priv->dev, + "kbus: Message queue for %s %u is full" + " (%u+%u%s > %u messages)\n", what, priv->id, + priv->message_count, + priv->outstanding_requests.count, + (is_reply ? "-1" : ""), priv->max_messages); + return true; + } +} + +/* + * Actually write to anyone interested in this message. + * + * Remember that the caller is going to free the message data after + * calling us, on the assumption that we're taking a copy... + * + * Returns 0 on success. + * + * If the message is a Request, and there is no replier for it, then we return + * -EADDRNOTAVAIL. + * + * If the message is a Reply, and the is sender is no longer connected (it has + * released its Ksock), then we return -EADDRNOTAVAIL. + * + * If the message couldn't be sent because some of the targets (those that we + * *have* to deliver to) had full queues, then it will return -EAGAIN or + * -EBUSY. If -EAGAIN is returned, then the caller should try again later, if + * -EBUSY then it should not. + * + * Otherwise, it returns a negative value for error. + */ +static int32_t kbus_write_to_recipients(struct kbus_private_data *priv, + struct kbus_dev *dev, + struct kbus_msg *msg) +{ + struct kbus_message_binding **listeners = NULL; + struct kbus_message_binding *replier = NULL; + struct kbus_private_data *reply_to = NULL; + ssize_t retval = 0; + int num_listeners; + int ii; + int num_sent = 0; /* # successfully "sent" */ + + int all_or_fail = msg->flags & KBUS_BIT_ALL_OR_FAIL; + int all_or_wait = msg->flags & KBUS_BIT_ALL_OR_WAIT; + + kbus_maybe_dbg(priv->dev, "kbus: all_or_fail %d, all_or_wait %d\n", + all_or_fail, all_or_wait); + + /* + * Remember that + * (a) a listener may occur more than once in our array, and + * (b) we have 0 or 1 repliers, but + * (c) the replier is *not* one of the listeners. + */ + num_listeners = kbus_find_listeners(dev, &listeners, &replier, + msg->name_len, msg->name_ref->name); + if (num_listeners < 0) { + kbus_maybe_dbg(priv->dev, + "kbus: Error %d finding listeners\n", + num_listeners); + + retval = num_listeners; + goto done_sending; + } + + /* + * In general, we don't mind if no-one is listening, but + * + * a. If we want a reply, we want there to be a replier + * b. If we *are* a reply, we want there to be an original sender + * c. If we have the "to" field set, and we want a reply, then we + * want that specific replier to exist + * + * We can check the first of those immediately. + */ + + if (msg->flags & KBUS_BIT_WANT_A_REPLY && replier == NULL) { + kbus_maybe_dbg(priv->dev, + "kbus: Message wants a reply, " + "but no replier\n"); + retval = -EADDRNOTAVAIL; + goto done_sending; + } + + /* And we need to add it to the queue for each interested party */ + + /* + * =================================================================== + * Check if the proposed recipients *can* receive + * =================================================================== + */ + + /* + * Are we replying to a sender's request? + * Replies are unusual in that the recipient will not normally have + * bound to the appropriate message name. + */ + if (kbus_message_is_reply(msg)) { + kbus_maybe_dbg(priv->dev, + "kbus: Considering sender-of-request %u\n", + msg->to); + + reply_to = kbus_find_private_data(priv, dev, msg->to); + if (reply_to == NULL) { + kbus_maybe_dbg(priv->dev, + "kbus: Can't find sender-of-request" + " %u\n", msg->to); + + /* We can't find the original Sender */ + retval = -EADDRNOTAVAIL; + goto done_sending; + } + + /* Are they expecting this reply? */ + if (kbus_find_msg_id(reply_to, &msg->in_reply_to)) { + /* No, so we aren't allowed to send it */ + retval = -ECONNREFUSED; + goto done_sending; + } + + if (kbus_queue_is_full(reply_to, "sender-of-request", true)) { + if (all_or_wait) + retval = -EAGAIN; /* try again later */ + else + retval = -EBUSY; + goto done_sending; + } + } + + /* Repliers only get request messages */ + if (replier && !(msg->flags & KBUS_BIT_WANT_A_REPLY)) + replier = NULL; + + /* + * And even then, only if they have room in their queue + * Note that it is *always* fatal (to this send) if we can't + * add a Request to a Replier's queue -- we just need to figure + * out what sort of error to return + */ + if (replier) { + kbus_maybe_dbg(priv->dev, "kbus: Considering replier %u\n", + replier->bound_to_id); + /* + * If the 'to' field was set, then we only want to send it if + * it is *that* specific replier (and otherwise we want to fail + * with "that's the wrong person for this (stateful) request"). + */ + if (msg->to && (replier->bound_to_id != msg->to)) { + + kbus_maybe_dbg(priv->dev, "kbus: ..Request to %u," + " but replier is %u\n", msg->to, + replier->bound_to_id); + + retval = -EPIPE; /* Well, sort of */ + goto done_sending; + } + + if (kbus_queue_is_full(replier->bound_to, "replier", false)) { + if (all_or_wait) + retval = -EAGAIN; /* try again later */ + else + retval = -EBUSY; + goto done_sending; + } + } + + for (ii = 0; ii < num_listeners; ii++) { + + kbus_maybe_dbg(priv->dev, "kbus: Considering listener %u\n", + listeners[ii]->bound_to_id); + + if (kbus_queue_is_full + (listeners[ii]->bound_to, "listener", false)) { + if (all_or_wait) { + retval = -EAGAIN; /* try again later */ + goto done_sending; + } else if (all_or_fail) { + retval = -EBUSY; + goto done_sending; + } else { + /* For now, just ignore *this* listener */ + listeners[ii] = NULL; + continue; + } + } + } + + /* + * =================================================================== + * Actually send the messages + * =================================================================== + */ + + /* + * Remember that kbus_push_message takes a copy of the message for us. + * + * This is inefficient, since otherwise we could keep a single copy of + * the message (or at least the message header) and just bump a + * reference count for each "use" of the message name/data. + * + * However, it also allows us to easily set the "needs a reply" flag + * (and associated data) when sending a "needs a reply" message to a + * replier, and *unset* the same when sending said message to "just" + * listeners... + * + * Be careful if altering this... + */ + + /* + * We know that kbus_push_message() can return 0 or -EFAULT. + * It seems sensible to treat that latter as a "local" error, as it + * means that our internals have gone wrong. Thus we don't need to + * generate a message for it. + */ + + /* If it's a reply message and we've got someone to reply to, send it */ + if (reply_to) { + retval = kbus_push_message(reply_to, msg, NULL, true); + if (retval == 0) { + num_sent++; + /* + * In which case, we *have* sent this reply, + * and can forget about needing to do so + * (there's not much we can do with an error + * in this, so just ignore it) + */ + (void)kbus_reply_now_sent(priv, &msg->in_reply_to); + } else { + goto done_sending; + } + } + + /* If it's a request, and we've got a replier for it, send it */ + if (replier) { + retval = + kbus_push_message(replier->bound_to, msg, replier, true); + if (retval) + goto done_sending; + + num_sent++; + /* And we'll need a reply for that, thank you */ + retval = kbus_remember_msg_id(priv, &msg->id); + if (retval) + /* + * Out of memory - what *can* we do? + * (basically, nothing, it's all gone horribly + * wrong) + */ + goto done_sending; + } + + /* For each listener, if they're still interested, send it */ + for (ii = 0; ii < num_listeners; ii++) { + struct kbus_message_binding *listener = listeners[ii]; + if (listener) { + retval = kbus_push_message(listener->bound_to, msg, + listener, false); + if (retval == 0) + num_sent++; + else + goto done_sending; + } + } + + retval = 0; + +done_sending: + kfree(listeners); + return retval; +} + +/* + * Handle moving over the next chunk of data bytes from the user. + */ +static int kbus_write_data_parts(struct kbus_private_data *priv, + const char __user *buf, + size_t buf_pos, size_t bytes_to_use) +{ + struct kbus_write_msg *this = &(priv->write); + + uint32_t num_parts = this->ref_data->num_parts; + size_t local_count = bytes_to_use; + size_t local_buf_pos = 0; + + kbus_maybe_dbg_write(priv->dev, + "kbus: %u/%u WRITE DATA PARTS buf_pos %u, " + "bytes_to_use %u\n", + (unsigned)priv->dev->index, (unsigned)priv->id, + (unsigned)buf_pos, (unsigned)bytes_to_use); + kbus_maybe_dbg_write(priv->dev, + "kbus: local_count = %u, local_buf_pos = %u\n", + (unsigned)local_count, (unsigned)local_buf_pos); + + while (local_count) { + unsigned ii = this->ref_data_index; + unsigned this_part_len; + size_t sofar, needed, to_use; + + unsigned *lengths = this->ref_data->lengths; + unsigned long *parts = this->ref_data->parts; + + if (ii == num_parts - 1) + this_part_len = this->ref_data->last_page_len; + else + this_part_len = KBUS_PART_LEN; + + sofar = lengths[ii]; + + needed = this_part_len - sofar; + to_use = min(needed, local_count); + + kbus_maybe_dbg_write(priv->dev, + "kbus: LOOP part %u/%u, tgt %p, sofar %u, needed %u," + " to_use %u\n", + ii + 1, num_parts, (void *)parts[ii], (unsigned)sofar, + (unsigned)needed, (unsigned)to_use); + + if (copy_from_user((char *)parts[ii] + sofar, + buf + buf_pos + local_buf_pos, to_use)) { + printk(KERN_ERR "kbus: copy from data failed" + " (part %d: %u of %u to %p + %u)\n", + this->ref_data_index, + (unsigned)to_use, (unsigned)local_count, + (void *)parts[ii], (unsigned)sofar); + return -EFAULT; + } + + lengths[ii] += to_use; + local_count -= to_use; + local_buf_pos += to_use; + + if (lengths[ii] == this_part_len) { + /* This part is full */ + this->ref_data_index++; + kbus_maybe_dbg_write(priv->dev, + "kbus: this part is full\n"); + } + } + kbus_maybe_dbg_write(priv->dev, + "kbus: %u/%u WRITE DATA PARTS is DONE\n", + priv->dev->index, priv->id); + return 0; +} + +/* + * Handle moving over the next chunk of bytes from the user to our message. + * + * 'buf' is the buffer of data the user gave us. + * + * 'buf_pos' is the offset in that buffer from which we are to take bytes. + * We alter that by how many bytes we do take. + * + * 'count' is the number of bytes we're still to take from 'buf'. We also + * alter 'count' by how many bytes we do take (downwards). + */ +static int kbus_write_parts(struct kbus_private_data *priv, + const char __user *buf, + size_t *buf_pos, size_t *count) +{ + struct kbus_write_msg *this = &(priv->write); + ssize_t retval = 0; + + size_t bytes_needed; /* ...to fill the current part */ + size_t bytes_to_use; /* ...from the user's data */ + + struct kbus_msg *msg = this->msg; + struct kbus_message_header *user_msg = + (struct kbus_message_header *)&this->user_msg; + + if (this->is_finished) { + printk(KERN_ERR "kbus: pid %u [%s]" + " Attempt to write data after the end guard in a" + " message (%u extra byte%s) - did you forget to" + " 'send'?\n", + current->pid, current->comm, + (unsigned)*count, *count == 1 ? "" : "s"); + return -EMSGSIZE; + } + kbus_maybe_dbg_write(priv->dev, + "kbus: %u/%u WRITE PARTS buf_pos %u, count %u\n", + priv->dev->index, priv->id, (unsigned)*buf_pos, + (unsigned)*count); + + switch (this->which) { + + case KBUS_PART_HDR: + bytes_needed = sizeof(*user_msg) - this->pos; + bytes_to_use = min(bytes_needed, *count); + + kbus_maybe_dbg_write(priv->dev, + "kbus: HDR bytes_needed %u, bytes_to_use %u\n", + (unsigned)bytes_needed, (unsigned)bytes_to_use); + kbus_report_write_msg(priv); + kbus_maybe_dbg_write(priv->dev, + "kbus: copy from user(%p + %u, %p + %u, %u)\n", + user_msg, this->pos, buf, (unsigned)*buf_pos, + (unsigned)bytes_to_use); + + if (copy_from_user((char *)user_msg + this->pos, + buf + *buf_pos, bytes_to_use)) { + printk(KERN_ERR + "kbus: copy from user failed (msg hdr: " + "%u of %u to %p + %u)\n", + (unsigned)bytes_to_use, (unsigned)*count, msg, + this->pos); + return -EFAULT; + } + if (bytes_needed == bytes_to_use) { + /* + * At this point, we can check the message header makes + * sense + */ + retval = kbus_check_message_written(this); + if (retval) + return retval; + + msg->id = user_msg->id; + msg->in_reply_to = user_msg->in_reply_to; + msg->to = user_msg->to; + msg->from = user_msg->from; + msg->orig_from = user_msg->orig_from; + msg->final_to = user_msg->final_to; + msg->extra = user_msg->extra; + msg->flags = user_msg->flags; + msg->name_len = user_msg->name_len; + msg->data_len = user_msg->data_len; + /* Leaving msg->name|data_ref still unset */ + + this->user_name_ptr = user_msg->name; + this->user_data_ptr = user_msg->data; + + if (user_msg->name) + /* + * If we're reading a "pointy" message header, + * then that's all we need - we shan't try to + * copy the message name and any data until the + * user says to SEND. + */ + this->is_finished = true; + else + this->pointers_are_local = true; + kbus_maybe_dbg_write(priv->dev, + "kbus: HDR finished (%s, %s)\n", + this->is_finished ? "finished" : "not finished", + this->pointers_are_local ? "local" : + "nonlocal"); + } + break; + + case KBUS_PART_NAME: + if (this->ref_name == NULL) { + char *name = kmalloc(msg->name_len + 1, GFP_KERNEL); + if (!name) { + printk(KERN_ERR "kbus: Cannot kmalloc" + " message name\n"); + return -ENOMEM; + } + name[msg->name_len] = 0; /* always */ + name[0] = 0; /* we don't know the name yet */ + this->ref_name = kbus_wrap_name_in_ref(name); + if (!this->ref_name) { + kfree(name); + printk(KERN_ERR "kbus: Cannot kmalloc ref to" + " message name\n"); + return -ENOMEM; + } + } + bytes_needed = msg->name_len - this->pos; + bytes_to_use = min(bytes_needed, *count); + + kbus_maybe_dbg_write(priv->dev, + "kbus: NAME bytes_needed %u, bytes_to_use %u\n", + (unsigned)bytes_needed, (unsigned)bytes_to_use); + + if (copy_from_user(this->ref_name->name + this->pos, + buf + *buf_pos, bytes_to_use)) { + printk(KERN_ERR "kbus: copy from user failed" + " (name: %d of %d to %p + %u)\n", + (unsigned)bytes_to_use, (unsigned)*count, + this->ref_name->name, this->pos); + return -EFAULT; + } + if (bytes_needed == bytes_to_use) { + kbus_maybe_dbg_write(priv->dev, + "kbus: NAME finished\n"); + /* + * We can check the name now it is in kernel space - we + * want to do this before we sort out the data, since + * that can involve a *lot* of copying... + */ + if (kbus_invalid_message_name + (this->ref_name->name, msg->name_len)) + return -EBADMSG; + + this->msg->name_ref = this->ref_name; + this->ref_name = NULL; + } + break; + + case KBUS_PART_NPAD: + bytes_needed = KBUS_PADDED_NAME_LEN(msg->name_len) - + msg->name_len - this->pos; + bytes_to_use = min(bytes_needed, *count); + kbus_maybe_dbg_write(priv->dev, + "kbus: NPAD bytes_needed %u, bytes_to_use %u\n", + (unsigned)bytes_needed, (unsigned)bytes_to_use); + break; + + case KBUS_PART_DATA: + if (msg->data_len == 0) { + bytes_needed = 0; + bytes_to_use = 0; + kbus_maybe_dbg_write(priv->dev, + "kbus: DATA bytes_needed %u, " + "bytes_to_use %u\n", + (unsigned)bytes_needed, (unsigned)bytes_to_use); + break; + } + if (this->ref_data == NULL) { + if (kbus_alloc_ref_data(priv, msg->data_len, + &this->ref_data)) + return -ENOMEM; + this->ref_data_index = 0; /* current part index */ + } + /* Overall, how far are we through the message's data? */ + bytes_needed = msg->data_len - this->pos; + bytes_to_use = min(bytes_needed, *count); + kbus_maybe_dbg_write(priv->dev, + "kbus: DATA bytes_needed %u, bytes_to_use %u\n", + (unsigned)bytes_needed, (unsigned)bytes_to_use); + /* So let's add 'bytes_to_use' bytes to our message data */ + retval = kbus_write_data_parts(priv, buf, *buf_pos, + bytes_to_use); + if (retval) { + kbus_lower_data_ref(this->ref_data); + this->ref_data = NULL; + return retval; + } + if (bytes_needed == bytes_to_use) { + kbus_maybe_dbg_write(priv->dev, + "kbus: DATA finished\n"); + /* Hooray - we've finished our data */ + this->msg->data_ref = this->ref_data; + this->ref_data = NULL; + } + break; + + case KBUS_PART_DPAD: + bytes_needed = KBUS_PADDED_DATA_LEN(msg->data_len) - + msg->data_len - this->pos; + bytes_to_use = min(bytes_needed, *count); + kbus_maybe_dbg_write(priv->dev, + "kbus: DPAD bytes_needed %u, bytes_to_use %u\n", + (unsigned)bytes_needed, (unsigned)bytes_to_use); + break; + + case KBUS_PART_FINAL_GUARD: + bytes_needed = 4 - this->pos; + bytes_to_use = min(bytes_needed, *count); + if (copy_from_user((char *)(&this->guard) + this->pos, + buf + *buf_pos, bytes_to_use)) { + printk(KERN_ERR "kbus: copy from user failed" + " (final guard: %u of %u to %p + %u)\n", + (unsigned)bytes_to_use, (unsigned)*count, + &this->guard, this->pos); + return -EFAULT; + } + if (bytes_needed == bytes_to_use) { + kbus_maybe_dbg_write(priv->dev, + "kbus: FINAL END GUARD finished\n"); + if (this->guard != KBUS_MSG_END_GUARD) { + printk(KERN_ERR "kbus: pid %u [%s]" + " (entire) message end guard is " + "%08x, not %08x\n", + current->pid, current->comm, + this->guard, KBUS_MSG_END_GUARD); + return -EINVAL; + } + this->is_finished = true; + } + break; + + default: + printk(KERN_ERR "kbus: Internal error in write: unexpected" + " message part %d\n", this->which); + return -EFAULT; /* what *should* it be? */ + } + + *count -= bytes_to_use; + *buf_pos += bytes_to_use; + + if (bytes_needed == bytes_to_use) { + this->which++; + this->pos = 0; + } else + this->pos += bytes_to_use; + + kbus_maybe_dbg_write(priv->dev, + "kbus: count = %u, buf_pos = %u, which = %d, pos = %u\n", + (unsigned)*count, (unsigned)*buf_pos, this->which, this->pos); + return 0; +} + +static ssize_t kbus_write(struct file *filp, const char __user *buf, + size_t count, loff_t *f_pos __maybe_unused) +{ + struct kbus_private_data *priv = filp->private_data; + struct kbus_dev *dev = priv->dev; + ssize_t retval = 0; + size_t bytes_left = count; + size_t buf_pos = 0; + + struct kbus_write_msg *this = &priv->write; + + if (mutex_lock_interruptible(&dev->mux)) + return -EAGAIN; + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u WRITE count %u, pos %d\n", + dev->index, priv->id, (unsigned)count, (int)*f_pos); + + /* + * If we've already started to try sending a message, we don't + * want to continue appending to it + */ + if (priv->sending) { + retval = -EALREADY; + goto done; + } + + if (this->msg == NULL) { + /* Clearly, the start of a new message */ + memset(this, 0, sizeof(*this)); + + /* This is the new (internal) message we're preparing */ + this->msg = kmalloc(sizeof(*(this->msg)), GFP_KERNEL); + if (!this->msg) { + retval = -ENOMEM; + goto done; + } + memset(this->msg, 0, sizeof(*(this->msg))); + kbus_report_write_msg(priv); + } + + while (bytes_left) { + retval = kbus_write_parts(priv, buf, &buf_pos, &bytes_left); + if (retval) + goto done; + } + + kbus_report_write_msg(priv); + +done: + kbus_maybe_dbg(priv->dev, "kbus: %u/%u WRITE ends with retval %d\n", + dev->index, priv->id, (int)retval); + + if (retval) + kbus_empty_write_msg(priv); + mutex_unlock(&dev->mux); + if (retval) + return retval; + else + return count; +} + +static ssize_t kbus_read(struct file *filp, char __user *buf, size_t count, + loff_t *f_pos __maybe_unused) +{ + struct kbus_private_data *priv = filp->private_data; + struct kbus_dev *dev = priv->dev; + struct kbus_read_msg *this = &(priv->read); + ssize_t retval = 0; + uint32_t len, left; + uint32_t which = this->which; + + if (mutex_lock_interruptible(&dev->mux)) + return -EAGAIN; /* Just try again later */ + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u READ count %u, pos %d\n", + dev->index, priv->id, (unsigned)count, (int)*f_pos); + + if (this->msg == NULL) { + /* No message to read at the moment */ + kbus_maybe_dbg(priv->dev, "kbus: Nothing to read\n"); + retval = 0; + goto done; + } + + /* + * Read each of the parts of a message until we're read 'count' + * characters, or run off the end of the message. + */ + while (which < KBUS_NUM_PARTS && count > 0) { + if (this->lengths[which] == 0) { + kbus_maybe_dbg(priv->dev, + "kbus: xx which %d, read_len[%d] %u\n", + which, which, this->lengths[which]); + this->pos = 0; + which++; + continue; + } + + if (which == KBUS_PART_DATA) { + struct kbus_data_ptr *dp = this->msg->data_ref; + + left = dp->lengths[this->ref_data_index] - this->pos; + len = min(left, (uint32_t) count); + kbus_maybe_dbg_read(priv->dev, + "kbus: xx which %d, part %d length %u, " + "pos %u, left %u, len %u, count %u\n", + which, this->ref_data_index, + dp->lengths[this->ref_data_index], + this->pos, left, len, (unsigned)count); + if (len) { + if (copy_to_user(buf, + (void *) + dp->parts[this->ref_data_index] + + this->pos, len)) { + printk(KERN_ERR + "kbus: error reading from " + "dev %u/%u\n", + dev->index, priv->id); + retval = -EFAULT; + goto done; + } + buf += len; + retval += len; + count -= len; + this->pos += len; + } + + if (this->pos == dp->lengths[this->ref_data_index]) { + this->pos = 0; + this->ref_data_index++; + } + if (this->ref_data_index == dp->num_parts) { + this->pos = 0; + which++; + } + } else { + left = this->lengths[which] - this->pos; + len = min(left, (uint32_t) count); + kbus_maybe_dbg_read(priv->dev, + "kbus: xx which %d, read_len[%d] %u, pos %u, " + "left %u, len %u, count %u\n", + which, which, this->lengths[which], this->pos, + left, len, (unsigned)count); + if (len) { + if (copy_to_user(buf, + this->parts[which] + this->pos, + len)) { + printk(KERN_ERR + "kbus: error reading from " + "dev %u/%u\n", + dev->index, priv->id); + retval = -EFAULT; + goto done; + } + buf += len; + retval += len; + count -= len; + this->pos += len; + } + + if (this->pos == this->lengths[which]) { + this->pos = 0; + which++; + } + } + } + + if (which < KBUS_NUM_PARTS) { + kbus_maybe_dbg_read(priv->dev, + "kbus: Read %d bytes, now in part %d, " + "read %d of %d\n", (int)retval, which, + this->pos, this->lengths[which]); + this->which = which; + } else { + kbus_maybe_dbg_read(priv->dev, + "kbus: Read %d bytes, finished\n", (int)retval); + kbus_empty_read_msg(priv); + } + +done: + mutex_unlock(&dev->mux); + return retval; +} + +static int kbus_bind(struct kbus_private_data *priv, + struct kbus_dev *dev, unsigned long arg) +{ + int retval = 0; + struct kbus_bind_request *bind; + char *name = NULL; + + bind = kmalloc(sizeof(*bind), GFP_KERNEL); + if (!bind) + return -ENOMEM; + if (copy_from_user(bind, (void __user *)arg, sizeof(*bind))) { + retval = -EFAULT; + goto done; + } + + if (bind->name_len == 0) { + kbus_maybe_dbg(dev, "kbus: bind name is length 0\n"); + retval = -EBADMSG; + goto done; + } else if (bind->name_len > KBUS_MAX_NAME_LEN) { + kbus_maybe_dbg(dev, "kbus: bind name is length %d\n", + bind->name_len); + retval = -ENAMETOOLONG; + goto done; + } + + name = kmalloc(bind->name_len + 1, GFP_KERNEL); + if (!name) { + retval = -ENOMEM; + goto done; + } + if (copy_from_user(name, (char __user *) bind->name, bind->name_len)) { + retval = -EFAULT; + goto done; + } + name[bind->name_len] = 0; + + if (kbus_bad_message_name(name, bind->name_len)) { + retval = -EBADMSG; + goto done; + } + + if (bind->is_replier && !strcmp(name, + KBUS_MSG_NAME_REPLIER_BIND_EVENT)) { + kbus_maybe_dbg(priv->dev, "kbus: cannot bind %s as a Replier\n", + KBUS_MSG_NAME_REPLIER_BIND_EVENT); + retval = -EBADMSG; + goto done; + } + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u BIND %c '%.*s'\n", + priv->dev->index, priv->id, + (bind->is_replier ? 'R' : 'L'), bind->name_len, name); + + retval = kbus_remember_binding(dev, priv, + bind->is_replier, bind->name_len, name); + if (retval == 0) + /* The binding will use our copy of the message name */ + name = NULL; + +done: + kfree(name); + kfree(bind); + return retval; +} + +static int kbus_unbind(struct kbus_private_data *priv, + struct kbus_dev *dev, unsigned long arg) +{ + int retval = 0; + struct kbus_bind_request *bind; + char *name = NULL; + uint32_t old_message_count = priv->message_count; + + bind = kmalloc(sizeof(*bind), GFP_KERNEL); + if (!bind) + return -ENOMEM; + if (copy_from_user(bind, (void __user *)arg, sizeof(*bind))) { + retval = -EFAULT; + goto done; + } + + if (bind->name_len == 0) { + kbus_maybe_dbg(priv->dev, "kbus: unbind name is length 0\n"); + retval = -EBADMSG; + goto done; + } else if (bind->name_len > KBUS_MAX_NAME_LEN) { + kbus_maybe_dbg(priv->dev, "kbus: unbind name is length %d\n", + bind->name_len); + retval = -ENAMETOOLONG; + goto done; + } + + name = kmalloc(bind->name_len + 1, GFP_KERNEL); + if (!name) { + retval = -ENOMEM; + goto done; + } + if (copy_from_user(name, (char __user *) bind->name, bind->name_len)) { + retval = -EFAULT; + goto done; + } + name[bind->name_len] = 0; + + if (kbus_bad_message_name(name, bind->name_len)) { + retval = -EBADMSG; + goto done; + } + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u UNBIND %c '%.*s'\n", + priv->dev->index, priv->id, + (bind->is_replier ? 'R' : 'L'), bind->name_len, name); + + retval = kbus_forget_binding(dev, priv, + bind->is_replier, bind->name_len, name); + + /* + * If we're unbinding from $.KBUS.ReplierBindEvent, and there + * are (or may be) any such kept for us on the unread Replier + * Unbind Event list, then we need to remove them as well... + * + * NOTE that the following only checks for exact matchs to + * $.KBUS.ReplierBindEvent, which should be sufficient... + */ + if (priv->maybe_got_unsent_unbind_msgs && + !strcmp(name, KBUS_MSG_NAME_REPLIER_BIND_EVENT)) + kbus_forget_my_unsent_unbind_msgs(priv); + + /* + * If that removed any messages from the message queue, then we have + * room to consider moving a message across from the unread Replier + * Unbind Event list + */ + if (priv->message_count < old_message_count && + priv->maybe_got_unsent_unbind_msgs) { + int rv = kbus_maybe_move_unsent_unbind_msg(priv); + /* If this fails, we're probably stumped */ + if (rv) + /* The best we can do is grumble gently. We still + * want to return retval, not rv. + */ + printk(KERN_ERR + "kbus: Failed to move unsent messages on " + "unbind (error %d)\n", -rv); + } + +done: + kfree(name); + kfree(bind); + return retval; +} + +static int kbus_replier(struct kbus_private_data *priv __maybe_unused, + struct kbus_dev *dev, unsigned long arg) +{ + struct kbus_private_data *replier; + struct kbus_bind_query *query; + char *name = NULL; + int retval = 0; + + query = kmalloc(sizeof(*query), GFP_KERNEL); + if (!query) + return -ENOMEM; + if (copy_from_user(query, (void __user *)arg, sizeof(*query))) { + retval = -EFAULT; + goto done; + } + + if (query->name_len == 0 || query->name_len > KBUS_MAX_NAME_LEN) { + kbus_maybe_dbg(priv->dev, "kbus: Replier name is length %d\n", + query->name_len); + retval = -ENAMETOOLONG; + goto done; + } + + name = kmalloc(query->name_len + 1, GFP_KERNEL); + if (!name) { + retval = -ENOMEM; + goto done; + } + if (copy_from_user(name, (char __user *) query->name, + query->name_len)) { + retval = -EFAULT; + goto done; + } + name[query->name_len] = 0; + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u REPLIER for '%.*s'\n", + priv->dev->index, priv->id, query->name_len, name); + + retval = kbus_find_replier(dev, &replier, query->name_len, name); + if (retval < 0) + goto done; + + if (retval) + query->return_id = replier->id; + else + query->return_id = 0; + /* + * Copy the whole structure back, rather than try to work out (in a + * guaranteed-safe manner) where the 'id' actually lives + */ + if (copy_to_user((void __user *)arg, query, sizeof(*query))) { + retval = -EFAULT; + goto done; + } +done: + kfree(name); + kfree(query); + return retval; +} + +/* + * Make the next message ready for reading by the user. + * + * Returns 0 if there is no next message, 1 if there is, and a negative value + * if there's an error. + */ +static int kbus_nextmsg(struct kbus_private_data *priv, + unsigned long arg) +{ + int retval = 0; + struct kbus_msg *msg; + struct kbus_read_msg *this = &(priv->read); + struct kbus_message_header *user_msg; + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u NEXTMSG\n", priv->dev->index, + priv->id); + + /* If we were partway through a message, lose it */ + if (this->msg) { + kbus_maybe_dbg(priv->dev, "kbus: Dropping partial message\n"); + kbus_empty_read_msg(priv); + } + + /* Have we got a next message? */ + msg = kbus_pop_message(priv); + if (msg == NULL) { + kbus_maybe_dbg(priv->dev, "kbus: No next message\n"); + /* + * A return value of 0 means no message, and that's + * what __put_user returns for success. + */ + return __put_user(0, (uint32_t __user *) arg); + } + kbus_maybe_dbg_read(priv->dev, "kbus: xx Setting up read_hdr\n"); + + user_msg = (struct kbus_message_header *)&this->user_hdr; + user_msg->start_guard = KBUS_MSG_START_GUARD; + user_msg->id = msg->id; + user_msg->in_reply_to = msg->in_reply_to; + user_msg->to = msg->to; + user_msg->from = msg->from; + user_msg->orig_from = msg->orig_from; + user_msg->final_to = msg->final_to; + user_msg->extra = msg->extra; + user_msg->flags = msg->flags; + user_msg->name_len = msg->name_len; + user_msg->data_len = msg->data_len; + user_msg->name = NULL; + user_msg->data = NULL; + user_msg->end_guard = KBUS_MSG_END_GUARD; + + this->msg = msg; /* Remember it so we can free it later */ + + this->parts[KBUS_PART_HDR] = (char *)user_msg; + this->parts[KBUS_PART_NAME] = msg->name_ref->name; + /* direct to the string */ + + this->parts[KBUS_PART_NPAD] = static_zero_padding; + + /* The data is treated specially - see kbus_read() */ + this->parts[KBUS_PART_DATA] = (char *)msg->data_ref; + + this->parts[KBUS_PART_DPAD] = static_zero_padding; + this->parts[KBUS_PART_FINAL_GUARD] = (char *)&static_end_guard; + + this->lengths[KBUS_PART_HDR] = sizeof(*user_msg); + this->lengths[KBUS_PART_NAME] = msg->name_len; + this->lengths[KBUS_PART_NPAD] = + KBUS_PADDED_NAME_LEN(msg->name_len) - msg->name_len; + + /* The data is treated specially - see kbus_read() */ + this->lengths[KBUS_PART_DATA] = msg->data_len; + this->lengths[KBUS_PART_DPAD] = + KBUS_PADDED_DATA_LEN(msg->data_len) - msg->data_len; + + this->lengths[KBUS_PART_FINAL_GUARD] = 4; + + /* And we'll be starting by writing out the first thing first */ + this->which = 0; + this->pos = 0; + this->ref_data_index = 0; + + if (KBUS_DEBUG_READ && priv->dev->verbose) { + int ii; + printk(KERN_DEBUG + "kbus: @@ Next message, %d parts, lengths\n", + KBUS_NUM_PARTS); + for (ii = 0; ii < KBUS_NUM_PARTS; ii++) + printk(KERN_DEBUG "kbus: %d: %6u @ %p\n", ii, + this->lengths[ii], this->parts[ii]); + printk(KERN_DEBUG "kbus: HDR: %u %u %u %u ...\n", + this->parts[KBUS_PART_HDR][0], + this->parts[KBUS_PART_HDR][1], + this->parts[KBUS_PART_HDR][2], + this->parts[KBUS_PART_HDR][3]); + printk(KERN_DEBUG "kbus: NAME: '%*s'\n", + msg->name_len, this->parts[KBUS_PART_NAME]); + printk(KERN_DEBUG "kbus read_msg @ %p\n", this); + printk(KERN_DEBUG "kbus user_hdr @ %p\n", + &(this->user_hdr)); + } + + /* + * If the message is a request (to us), then this is the approriate + * point to add it to our list of "requests we've read but not yet + * replied to" -- although that *sounds* as if we should be doing it in + * kbus_read, we might never get round to reading the content of the + * message (we might call NEXTMSG again, or DISCARD), and also + * kbus_read can get called multiple times for a single message body. + * If we do our remembering here, then we guarantee to get one memory + * for each request, as it leaves the message queue and is (in whatever + * way) dealt with. + */ + if (msg->flags & KBUS_BIT_WANT_YOU_TO_REPLY) { + retval = kbus_reply_needed(priv, msg); + /* If it couldn't malloc, there's not much we can do, + * it's fairly fatal */ + if (retval) + return retval; + } + + /* + * If we (maybe) have any unread Replier Unbind Event messages, + * we now have room to copy one across to the message list + */ + kbus_maybe_dbg(priv->dev, + "kbus: ++ maybe_got_unsent_unbind_msgs %d\n", + priv->maybe_got_unsent_unbind_msgs); + + if (priv->maybe_got_unsent_unbind_msgs) { + retval = kbus_maybe_move_unsent_unbind_msg(priv); + /* If this fails, we're probably stumped */ + if (retval) + return retval; + } + + retval = __put_user(KBUS_ENTIRE_MSG_LEN(msg->name_len, msg->data_len), + (uint32_t __user *) arg); + if (retval) + return retval; + return 1; /* We had a message */ +} + +/* How much of the current message is left to read? */ +static uint32_t kbus_lenleft(struct kbus_private_data *priv) +{ + struct kbus_read_msg *this = &(priv->read); + if (this->msg) { + int ii, jj; + uint32_t sofar = 0; + uint32_t total = KBUS_ENTIRE_MSG_LEN(this->msg->name_len, + this->msg->data_len); + /* Add up the items we're read all of, so far */ + for (ii = 0; ii < this->which; ii++) { + if (this->which == KBUS_PART_DATA && + this->msg->data_len > 0) { + struct kbus_data_ptr *dp = this->msg->data_ref; + for (jj = 0; jj < this->ref_data_index; jj++) + sofar += dp->lengths[jj]; + if (this->ref_data_index < dp->num_parts) + sofar += this->pos; + } else { + sofar += this->lengths[ii]; + } + } + /* Plus what we're read of the last one */ + if (this->which < KBUS_NUM_PARTS) { + if (this->which == KBUS_PART_DATA && + this->msg->data_len > 0) { + struct kbus_data_ptr *dp = this->msg->data_ref; + for (jj = 0; jj < this->ref_data_index; jj++) + sofar += dp->lengths[jj]; + if (this->ref_data_index < dp->num_parts) + sofar += this->pos; + } else { + sofar += this->pos; + } + } + return total - sofar; + } + return 0; /* no message => nothing to read */ +} + +/* + * Allocate the data arrays we need to hold reference-counted data, possibly + * spread over multiple pages. 'data_len' is from the message header. + * + * Note that the 'lengths[n]' field to each page 'n' will be set to zero. + */ +static int kbus_alloc_ref_data(struct kbus_private_data *priv __maybe_unused, + uint32_t data_len, + struct kbus_data_ptr **ret_ref_data) +{ + int num_parts = 0; + unsigned long *parts = NULL; + unsigned *lengths = NULL; + unsigned last_page_len = 0; + struct kbus_data_ptr *ref_data = NULL; + int as_pages; + int ii; + + *ret_ref_data = NULL; + + num_parts = (data_len + KBUS_PART_LEN - 1) / KBUS_PART_LEN; + + /* + * To save recalculating the length of the last page every time + * we're interested, get it right once and for all. + */ + last_page_len = data_len - (num_parts - 1) * KBUS_PART_LEN; + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u Allocate ref data: part=%lu, " + "threshold=%lu, data_len %u -> num_parts %d\n", + priv->dev->index, priv->id, KBUS_PART_LEN, + KBUS_PAGE_THRESHOLD, data_len, num_parts); + + parts = kmalloc(sizeof(*parts) * num_parts, GFP_KERNEL); + if (!parts) + return -ENOMEM; + lengths = kmalloc(sizeof(*lengths) * num_parts, GFP_KERNEL); + if (!lengths) { + kfree(parts); + return -ENOMEM; + } + + if (num_parts == 1 && data_len < KBUS_PAGE_THRESHOLD) { + /* A single part in "simple" memory */ + as_pages = false; + parts[0] = (unsigned long)kmalloc(data_len, GFP_KERNEL); + if (!parts[0]) { + kfree(lengths); + kfree(parts); + return -ENOMEM; + } + lengths[0] = 0; + } else { + /* + * One or more pages + * + * For simplicity, we make all of our pages be full pages. + * In theory, we could use the same rules for the last page + * as we do if we only have a single page - but for the + * moment, we're not bothering. + * + * This means that the 'last_page_len' is strictly theoretical + * for the moment... + */ + as_pages = true; + for (ii = 0; ii < num_parts; ii++) { + parts[ii] = __get_free_page(GFP_KERNEL); + if (!parts[ii]) { + int jj; + for (jj = 0; jj < ii; jj++) + free_page(parts[jj]); + kfree(lengths); + kfree(parts); + return -ENOMEM; + } + lengths[ii] = 0; + } + } + ref_data = kbus_wrap_data_in_ref(as_pages, num_parts, parts, lengths, + last_page_len); + if (!ref_data) { + int jj; + if (as_pages) + for (jj = 0; jj < num_parts; jj++) + free_page(parts[jj]); + else + kfree((void *)parts[0]); + kfree(lengths); + kfree(parts); + return -ENOMEM; + } + *ret_ref_data = ref_data; + return 0; +} + +/* + * Does what it says on the box - take the user data and promote it to kernel + * space, as a reference counted quantity, possibly spread over multiple pages. + */ +static int kbus_wrap_user_data(struct kbus_private_data *priv, + uint32_t data_len, + void *user_data_ptr, + struct kbus_data_ptr **new_data) +{ + struct kbus_data_ptr *ref_data = NULL; + int num_parts; + unsigned long *parts; + unsigned *lengths; + int ii; + uint8_t __user *data_ptr; + + int retval = kbus_alloc_ref_data(priv, data_len, &ref_data); + if (retval) + return retval; + + num_parts = ref_data->num_parts; + lengths = ref_data->lengths; + parts = ref_data->parts; + + kbus_maybe_dbg(priv->dev, "kbus: @@ copying %s\n", + ref_data->as_pages ? "as pages" : "as kmalloc'ed data"); + + /* Given all of the *space* for our data, populate it */ + data_ptr = (void __user *) user_data_ptr; + for (ii = 0; ii < num_parts; ii++) { + unsigned len; + if (ii == num_parts - 1) + len = ref_data->last_page_len; + else + len = KBUS_PART_LEN; + + kbus_maybe_dbg(priv->dev, + "kbus: @@ %d: copy %d bytes " + "from user address %lu\n", + ii, len, parts[ii]); + + if (copy_from_user((void *)parts[ii], data_ptr, len)) { + kbus_lower_data_ref(ref_data); + return -EFAULT; + } + lengths[ii] = len; + data_ptr += len; + } + *new_data = ref_data; + return 0; +} + +/* + * Given a "pointy" message header, copy the message name and data from + * user space into kernel space. + * + * The message name is copied as a reference-counted string. + * + * The message data (if any) is copied as reference-counted data. + * + * Also checks the legality of the message name, since we need the name in + * kernel space to do that, but prefer to do the check before copying any + * data (which can be expensive). + */ +static int kbus_copy_pointy_parts(struct kbus_private_data *priv, + struct kbus_write_msg *this) +{ + struct kbus_msg *msg = this->msg; + char *new_name = NULL; + struct kbus_name_ptr *name_ref; + struct kbus_data_ptr *new_data = NULL; + + /* First, let's deal with the name */ + new_name = kmalloc(msg->name_len + 1, GFP_KERNEL); + if (!new_name) + return -ENOMEM; + if (copy_from_user + (new_name, (void __user *)this->user_name_ptr, msg->name_len + 1)) { + kfree(new_name); + return -EFAULT; + } + + /* + * We can check the name now it is in kernel space - we want + * to do this before we sort out the data, since that can involve + * a *lot* of copying... + */ + if (kbus_invalid_message_name(new_name, msg->name_len)) { + kfree(new_name); + return -EBADMSG; + } + name_ref = kbus_wrap_name_in_ref(new_name); + if (!name_ref) { + kfree(new_name); + return -ENOMEM; + } + + /* Now for the data. */ + if (msg->data_len) { + int retval = kbus_wrap_user_data(priv, msg->data_len, + this->user_data_ptr, + &new_data); + if (retval) { + kbus_lower_name_ref(name_ref); + return retval; + } + } + + kbus_maybe_dbg(priv->dev, "kbus: 'pointy' message normalised\n"); + + msg->name_ref = name_ref; + msg->data_ref = new_data; + + this->user_name_ptr = NULL; + this->user_data_ptr = NULL; + this->pointers_are_local = true; + + return 0; +} + +static void kbus_discard(struct kbus_private_data *priv) +{ + kbus_empty_write_msg(priv); + priv->sending = false; +} + +/* + * Returns 0 for success, and a negative value if there's an error. + */ +static int kbus_send(struct kbus_private_data *priv, + struct kbus_dev *dev, unsigned long arg) +{ + ssize_t retval = 0; + struct kbus_msg *msg = priv->write.msg; + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u SEND\n", priv->dev->index, + priv->id); + + if (priv->write.msg == NULL) + return -ENOMSG; + + if (!priv->write.is_finished) { + printk(KERN_ERR "kbus: pid %u [%s]" + " message not finished (in part %d of message)\n", + current->pid, current->comm, priv->write.which); + retval = -EINVAL; + goto done; + } + + /* + * Users are not allowed to send messages marked as "synthetic" + * (since, after all, if the user sends it, it is not). However, + * it's possible that, in good faith, they re-sent a synthetic + * message that they received earlier, so we shall take care to + * unset the bit, if necessary. + */ + if (KBUS_BIT_SYNTHETIC & msg->flags) + msg->flags &= ~KBUS_BIT_SYNTHETIC; + + /* + * The "extra" field is reserved for future expansion, so for the + * moment we always zero it (this stops anyone from trying to take + * advantage of it, and getting caught out when we decide WE want it) + */ + msg->extra = 0; + + /* + * The message header is already in kernel space (thanks to kbus_write), + * but if it's a "pointy" message, the name and data are not. So let's + * fix that. + * + * Note that we *always* end up with a message header containing + * pointers to (copies of) the name and (if given) data, and the + * data reference counted, and maybe split over multiple pages. + * + * Note that if this is a message we already tried to send + * earlier, any "pointy" parts would have been copied earlier, + * hence the check we actually make. + */ + if (!priv->write.pointers_are_local) { + retval = kbus_copy_pointy_parts(priv, &priv->write); + if (retval) + goto done; + } + + /* ================================================================= */ + /* + * If this message is a Request, then we can't send it until/unless + * we've got room in our message queue to receive the Reply. + * + * We do this check here, rather than in kbus_write_to_recipients, + * because: + * + * a) kbus_write_to_recipients gets (re)called by the POLL interface, + * and at that stage KBUS *knows* that there is room for the + * message concerned (so the checking code would need to know not + * to check) + * + * b) If the check fails, we do not want to consider ourselves in + * "sending" state, since we can't afford to block, because it's + * *this Ksock* that needs to do some reading to clear the relevant + * queue, and it can't do that if it's blocking. So we'd either + * need to handle that (somehow), or just do the check here. + * + * Similarly, we don't finalise the message (put in its "from" and "id" + * fields) until we pass this test. + */ + if ((msg->flags & KBUS_BIT_WANT_A_REPLY) && + kbus_queue_is_full(priv, "sender", false)) { + printk(KERN_ERR "kbus: %u/%u Unable to send Request because no" + " room for a Reply in sender's message queue\n", + priv->dev->index, priv->id); + retval = -ENOLCK; + goto done; + } + /* ================================================================= */ + + /* So, we're actually ready to SEND! */ + + /* The message needs to say it is from us */ + msg->from = priv->id; + + /* + * If we've already tried to send this message earlier (and + * presumably failed with -EAGAIN), then we don't need to give + * it a message id, because it already has one... + */ + if (!priv->sending) { + /* The message seems well formed, give it an id if necessary */ + if (msg->id.network_id == 0) + msg->id.serial_num = kbus_next_serial_num(dev); + } + + /* Also, remember this as the "message we last (tried to) send" */ + priv->last_msg_id_sent = msg->id; + + /* + * Figure out who should receive this message, and write it to them + */ + retval = kbus_write_to_recipients(priv, dev, msg); + +done: + /* + * -EAGAIN means we were blocked from sending, and the caller + * should try again (as one might expect). + */ + if (retval == -EAGAIN) + /* Remember we're still trying to send this message */ + priv->sending = true; + else + /* We've now finished with our copy of the message header */ + kbus_discard(priv); + + if (retval == 0 || retval == -EAGAIN) + if (copy_to_user((void __user *)arg, &priv->last_msg_id_sent, + sizeof(priv->last_msg_id_sent))) + retval = -EFAULT; + return retval; +} + +static int kbus_maxmsgs(struct kbus_private_data *priv, + unsigned long arg) +{ + int retval = 0; + uint32_t requested_max; + + retval = __get_user(requested_max, (uint32_t __user *) arg); + if (retval) + return retval; + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u MAXMSGS requests %u (was %u)\n", + priv->dev->index, priv->id, + requested_max, priv->max_messages); + + /* A value of 0 is just a query for what the current length is */ + if (requested_max > 0) + priv->max_messages = requested_max; + + return __put_user(priv->max_messages, (uint32_t __user *) arg); +} + +static int kbus_nummsgs(struct kbus_private_data *priv, + struct kbus_dev *dev __maybe_unused, unsigned long arg) +{ + uint32_t count = priv->message_count; + + if (priv->maybe_got_unsent_unbind_msgs) { + kbus_maybe_dbg(dev, "kbus: %u/%u NUMMSGS 'main' count %u\n", + dev->index, priv->id, count); + count += kbus_count_unsent_unbind_msgs(priv); + } + + kbus_maybe_dbg(dev, "kbus: %u/%u NUMMSGS %u\n", + dev->index, priv->id, count); + + return __put_user(count, (uint32_t __user *) arg); +} + +static int kbus_onlyonce(struct kbus_private_data *priv, + unsigned long arg) +{ + int retval = 0; + uint32_t only_once; + int old_value = priv->messages_only_once; + + retval = __get_user(only_once, (uint32_t __user *) arg); + if (retval) + return retval; + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u ONLYONCE requests %u (was %d)\n", + priv->dev->index, priv->id, only_once, old_value); + + switch (only_once) { + case 0: + priv->messages_only_once = false; + break; + case 1: + priv->messages_only_once = true; + break; + case 0xFFFFFFFF: + break; + default: + return -EINVAL; + } + + return __put_user(old_value, (uint32_t __user *) arg); +} + +static int kbus_set_verbosity(struct kbus_private_data *priv, + unsigned long arg) +{ + int retval = 0; + uint32_t verbose; + int old_value = priv->dev->verbose; + + retval = __get_user(verbose, (uint32_t __user *) arg); + if (retval) + return retval; + + /* + * If we're *leaving* verbose mode, we would say so (!), + * and we should arguably announce when we enter it as well... + */ + if (KBUS_DEBUG_ENABLED) + printk(KERN_INFO "kbus: %u/%u VERBOSE requests %u (was %d)\n", + priv->dev->index, priv->id, verbose, old_value); + + switch (verbose) { + case 0: + priv->dev->verbose = false; + break; + case 1: + priv->dev->verbose = true; + break; + case 0xFFFFFFFF: + break; + default: + return -EINVAL; + } + + return __put_user(old_value, (uint32_t __user *) arg); +} + +/* Report all existing replier bindings to the requester */ +static int kbus_report_existing_binds(struct kbus_private_data *priv, + struct kbus_dev *dev) +{ + struct kbus_message_binding *ptr; + struct kbus_message_binding *next; + + list_for_each_entry_safe(ptr, next, &dev->bound_message_list, list) { + struct kbus_msg *new_msg; + int retval; + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u Report %c '%.*s'\n", + dev->index, priv->id, (ptr->is_replier ? 'R' : 'L'), + ptr->name_len, ptr->name); + + if (!ptr->is_replier) + continue; + + new_msg = kbus_new_synthetic_bind_message(ptr->bound_to, true, + ptr->name_len, ptr->name); + if (new_msg == NULL) + return -ENOMEM; + + /* + * It is perhaps a bit inefficient to check this per binding, + * but it saves us doing two passes through the list. + */ + if (kbus_queue_is_full(priv, "limpet", false)) { + /* Giving up is probably the best we can do */ + kbus_free_message(new_msg); + return -EBUSY; + } + + retval = kbus_push_message(priv, new_msg, NULL, false); + + kbus_free_message(new_msg); + if (retval) + return retval; + } + return 0; +} + +static int kbus_set_report_binds(struct kbus_private_data *priv, + struct kbus_dev *dev, unsigned long arg) +{ + int retval = 0; + uint32_t report_replier_binds; + int old_value = priv->dev->report_replier_binds; + + retval = __get_user(report_replier_binds, (uint32_t __user *) arg); + if (retval) + return retval; + + kbus_maybe_dbg(priv->dev, + "kbus: %u/%u REPORTREPLIERBINDS requests %u (was %d)\n", + priv->dev->index, priv->id, report_replier_binds, + old_value); + + switch (report_replier_binds) { + case 0: + priv->dev->report_replier_binds = false; + break; + case 1: + priv->dev->report_replier_binds = true; + /* And report the current state of bindings... */ + retval = kbus_report_existing_binds(priv, dev); + if (retval) + return retval; + break; + case 0xFFFFFFFF: + break; + default: + return -EINVAL; + } + + return __put_user(old_value, (uint32_t __user *) arg); +} + +static long kbus_ioctl(struct file *filp, unsigned int cmd, unsigned long arg) +{ + int err = 0; + int retval = 0; + struct kbus_private_data *priv = filp->private_data; + struct kbus_dev *dev = priv->dev; + uint32_t id = priv->id; + + if (_IOC_TYPE(cmd) != KBUS_IOC_MAGIC) + return -ENOTTY; + if (_IOC_NR(cmd) > KBUS_IOC_MAXNR) + return -ENOTTY; + /* + * Check our arguments at least vaguely match. Note that VERIFY_WRITE + * allows R/W transfers. Remember that 'type' is user-oriented, while + * access_ok is kernel-oriented, so the concept of "read" and "write" + * is reversed + */ + if (_IOC_DIR(cmd) & _IOC_READ) + err = !access_ok(VERIFY_WRITE, (void __user *)arg, + _IOC_SIZE(cmd)); + else if (_IOC_DIR(cmd) & _IOC_WRITE) + err = !access_ok(VERIFY_READ, (void __user *)arg, + _IOC_SIZE(cmd)); + if (err) + return -EFAULT; + + if (mutex_lock_interruptible(&dev->mux)) + return -ERESTARTSYS; + + switch (cmd) { + + case KBUS_IOC_RESET: + /* This is currently a no-op, but may be useful later */ + kbus_maybe_dbg(priv->dev, "kbus: %u/%u RESET\n", dev->index, + id); + break; + + case KBUS_IOC_BIND: + /* + * BIND: indicate that a file wants to receive messages of a + * given name + */ + retval = kbus_bind(priv, dev, arg); + break; + + case KBUS_IOC_UNBIND: + /* + * UNBIND: indicate that a file no longer wants to receive + * messages of a given name + */ + retval = kbus_unbind(priv, dev, arg); + break; + + case KBUS_IOC_KSOCKID: + /* + * What is the "Ksock id" for this file descriptor + */ + kbus_maybe_dbg(priv->dev, "kbus: %u/%u KSOCKID %u\n", + dev->index, id, id); + retval = __put_user(id, (uint32_t __user *) arg); + break; + + case KBUS_IOC_REPLIER: + /* + * Who (if anyone) is bound to reply to this message? + * arg in: message name + * arg out: listener id + * return: 0 means no-one, 1 means someone + * We can't just return the id as the return value of the ioctl, + * because it's an unsigned int, and the ioctl return must be + * signed... + */ + retval = kbus_replier(priv, dev, arg); + break; + + case KBUS_IOC_NEXTMSG: + /* + * Get the next message ready to be read, and return its + * length. + * + * arg in: none + * arg out: number of bytes in next message + * retval: 0 if no next message, 1 if there is a next message, + * negative value if there's an error. + */ + retval = kbus_nextmsg(priv, arg); + break; + + case KBUS_IOC_LENLEFT: + /* How many bytes are left to read in the current message? */ + { + uint32_t left = kbus_lenleft(priv); + kbus_maybe_dbg(priv->dev, "kbus: %u/%u LENLEFT %u\n", + dev->index, id, left); + retval = __put_user(left, (uint32_t __user *) arg); + } + break; + + case KBUS_IOC_SEND: + /* + * Send the curent message, we've finished writing it. + * + * arg in: + * arg out: the message id of said message + * retval: negative for bad message, etc., 0 otherwise + */ + retval = kbus_send(priv, dev, arg); + break; + + case KBUS_IOC_DISCARD: + /* Throw away the message we're currently writing. */ + kbus_maybe_dbg(priv->dev, "kbus: %u/%u DISCARD\n", dev->index, + id); + kbus_discard(priv); + break; + + case KBUS_IOC_LASTSENT: + /* + * What was the message id of the last message written to this + * file descriptor? Before any messages have been written to + * this file descriptor, this ioctl will return {0,0). + */ + kbus_maybe_dbg(priv->dev, "kbus: %u/%u LASTSENT %u:%u\n", + dev->index, id, + priv->last_msg_id_sent.network_id, + priv->last_msg_id_sent.serial_num); + if (copy_to_user((void __user *)arg, &priv->last_msg_id_sent, + sizeof(priv->last_msg_id_sent))) + retval = -EFAULT; + break; + + case KBUS_IOC_MAXMSGS: + /* + * Set (and/or query) maximum number of messages in this + * interfaces queue. + * + * arg in: 0 (for query) or maximum number wanted + * arg out: maximum number allowed + * return: 0 means OK, otherwise not OK + */ + retval = kbus_maxmsgs(priv, arg); + break; + + case KBUS_IOC_NUMMSGS: + /* How many messages are in our queue? + * + * arg out: maximum number allowed + * return: 0 means OK, otherwise not OK + */ + retval = kbus_nummsgs(priv, dev, arg); + break; + + case KBUS_IOC_UNREPLIEDTO: + /* How many Requests (to us) do we still owe Replies to? */ + kbus_maybe_dbg(priv->dev, "kbus: %u/%u UNREPLIEDTO %d\n", + dev->index, id, priv->num_replies_unsent); + retval = __put_user(priv->num_replies_unsent, + (uint32_t __user *) arg); + break; + + case KBUS_IOC_MSGONLYONCE: + /* + * Should we receive a given message only once? + * + * arg in: 0 (for no), 1 (for yes), 0xFFFFFFFF (for query) + * arg out: the previous value, before we were called + * return: 0 means OK, otherwise not OK + */ + retval = kbus_onlyonce(priv, arg); + break; + + case KBUS_IOC_VERBOSE: + /* + * Should we printk verbose messages? + * + * arg in: 0 (for no), 1 (for yes), 0xFFFFFFFF (for query) + * arg out: the previous value, before we were called + * return: 0 means OK, otherwise not OK + */ + retval = kbus_set_verbosity(priv, arg); + break; + + case KBUS_IOC_NEWDEVICE: + /* + * Request a new device + * + * arg out: the new device number + * return: 0 means OK, otherwise not OK. + */ + kbus_maybe_dbg(priv->dev, "kbus: %u/%u NEWDEVICE %d\n", + dev->index, id, kbus_num_devices); + retval = kbus_setup_new_device(kbus_num_devices); + if (retval > 0) { + kbus_num_devices++; + retval = __put_user(kbus_num_devices - 1, + (uint32_t __user *) arg); + } + break; + + case KBUS_IOC_REPORTREPLIERBINDS: + /* + * Should we report Replier bind/unbind events? + * + * arg in: 0 (for no), 1 (for yes), 0xFFFFFFFF (for query) + * arg out: the previous value, before we were called + * return: 0 means OK, otherwise not OK + */ + retval = kbus_set_report_binds(priv, dev, arg); + break; + + default: + /* *Should* be redundant, if we got our range checks right */ + retval = -ENOTTY; + break; + } + + mutex_unlock(&dev->mux); + return retval; +} + +/* + * Try sending the (current waiting to be sent) message + * + * Returns true if the message has either been successfully sent, or an error + * occcurred (which has been dealt with) and there is no longer a current + * message. + * + * Returns false if we hit EAGAIN (again) and we're still trying to send the + * current message. + */ +static int kbus_poll_try_send_again(struct kbus_private_data *priv, + struct kbus_dev *dev) +{ + int retval; + struct kbus_msg *msg = priv->write.msg; + + retval = kbus_write_to_recipients(priv, dev, msg); + + switch (-retval) { + case 0: /* All is well, nothing to do */ + break; + case EAGAIN: /* Still blocked by *someone* - nowt to do */ + break; + case EADDRNOTAVAIL: + /* + * It's a Request and there's no Replier (presumably there was + * when the initial SEND was done, but now they've gone away). + * A Request *needs* a Reply... + */ + kbus_push_synthetic_message(dev, 0, msg->from, msg->id, + KBUS_MSG_NAME_REPLIER_DISAPPEARED); + retval = 0; + break; + default: + /* + * Send *failed* - what can we do? + * Not much, perhaps, but we must ensure that a Request gets + * (some sort of) reply + */ + if (msg->flags & KBUS_BIT_WANT_A_REPLY) + kbus_push_synthetic_message(dev, 0, msg->from, msg->id, + KBUS_MSG_NAME_ERROR_SENDING); + retval = 0; + break; + } + + if (retval == 0) { + kbus_discard(priv); + return true; + } + return false; +} + +static unsigned int kbus_poll(struct file *filp, poll_table * wait) +{ + struct kbus_private_data *priv = filp->private_data; + struct kbus_dev *dev = priv->dev; + unsigned mask = 0; + + mutex_lock(&dev->mux); + + kbus_maybe_dbg(priv->dev, "kbus: %u/%u POLL\n", dev->index, priv->id); + + /* + * Did I wake up because there's a message available to be read? + */ + if (priv->message_count != 0) + mask |= POLLIN | POLLRDNORM; /* readable */ + + /* + * Did I wake up because someone said they had space for a message on + * their message queue (where there wasn't space before)? + * + * And if that is the case, if we're opened for write and have a + * message waiting to be sent, can we now send it? + * + * The simplest way to find out is just to try again. + */ + if (filp->f_mode & FMODE_WRITE) { + int writable = true; + if (priv->sending) + writable = kbus_poll_try_send_again(priv, dev); + if (writable) + mask |= POLLOUT | POLLWRNORM; + } + + /* Wait until someone has a message waiting to be read */ + poll_wait(filp, &priv->read_wait, wait); + + /* Wait until someone has a space into which a message can be pushed */ + if (priv->sending) + poll_wait(filp, &dev->write_wait, wait); + + mutex_unlock(&dev->mux); + return mask; +} + +/* File operations for /dev/kbus */ +static const struct file_operations kbus_fops = { + .owner = THIS_MODULE, + .read = kbus_read, + .write = kbus_write, + .unlocked_ioctl = kbus_ioctl, + .poll = kbus_poll, + .open = kbus_open, + .release = kbus_release, +}; + +static void kbus_setup_cdev(struct kbus_dev *dev, int devno) +{ + int err; + + /* + * Remember to initialise the mutex *before* making the device + * available! + */ + mutex_init(&dev->mux); + + /* + * This seems like a sensible place to setup other device specific + * stuff, too. + */ + INIT_LIST_HEAD(&dev->bound_message_list); + INIT_LIST_HEAD(&dev->open_ksock_list); + INIT_LIST_HEAD(&dev->unsent_unbind_msg_list); + + init_waitqueue_head(&dev->write_wait); + + dev->next_ksock_id = 0; + dev->next_msg_serial_num = 0; + + cdev_init(&dev->cdev, &kbus_fops); + dev->cdev.owner = THIS_MODULE; + + err = cdev_add(&dev->cdev, devno, 1); + if (err) + printk(KERN_ERR "Error %d adding kbus0 as a character device\n", + err); +} + +static void kbus_teardown_cdev(struct kbus_dev *dev) +{ + cdev_del(&dev->cdev); + + kbus_forget_all_bindings(dev); + kbus_forget_all_open_ksocks(dev); + kbus_forget_unsent_unbind_msgs(dev); +} + +/* ========================================================================= */ +/* PROC */ + +/* + * Report on the current bindings, via /proc/kbus/bindings + */ + +static int kbus_binding_seq_show(struct seq_file *s, void *v __always_unused) +{ + int ii; + + /* We report on all of the KBUS devices */ + for (ii = 0; ii < kbus_num_devices; ii++) { + struct kbus_dev *dev = kbus_devices[ii]; + + struct kbus_message_binding *ptr; + struct kbus_message_binding *next; + + if (mutex_lock_interruptible(&dev->mux)) + return -ERESTARTSYS; + + seq_printf(s, + "# is bound to in " + " as for \n"); + + list_for_each_entry_safe(ptr, next, &dev->bound_message_list, + list) { + seq_printf(s, "%3u: %8u %8lu %c %.*s\n", dev->index, + ptr->bound_to_id, + (long unsigned)ptr->bound_to->pid, + (ptr->is_replier ? 'R' : 'L'), + ptr->name_len, ptr->name); + } + + mutex_unlock(&dev->mux); + } + return 0; +} + +static int kbus_proc_bindings_open(struct inode *inode __always_unused, + struct file *file) +{ + return single_open(file, kbus_binding_seq_show, NULL); +} + +static const struct file_operations kbus_proc_binding_file_ops = { + .owner = THIS_MODULE, + .open = kbus_proc_bindings_open, + .read = seq_read, + .llseek = seq_lseek, + .release = seq_release +}; + +static struct proc_dir_entry +*kbus_create_proc_binding_file(struct proc_dir_entry *directory) +{ + struct proc_dir_entry *entry = + create_proc_entry("bindings", 0, directory); + if (entry) + entry->proc_fops = &kbus_proc_binding_file_ops; + return entry; +} + +/* + * Report on whatever statistics seem like they might be useful, + * via /proc/kbus/stats + */ + +static int kbus_stats_seq_show(struct seq_file *s, void *v __always_unused) +{ + int ii; + + /* We report on all of the KBUS devices */ + for (ii = 0; ii < kbus_num_devices; ii++) { + struct kbus_dev *dev = kbus_devices[ii]; + + struct kbus_private_data *ptr; + struct kbus_private_data *next; + + if (mutex_lock_interruptible(&dev->mux)) + return -ERESTARTSYS; + + seq_printf(s, + "dev %2u: next ksock %u next msg %u " + "unsent unbindings %u%s\n", + dev->index, dev->next_ksock_id, + dev->next_msg_serial_num, + dev->unsent_unbind_msg_count, + (dev->unsent_unbind_is_tragic ? "(gone tragic)" : "")); + + list_for_each_entry_safe(ptr, next, + &dev->open_ksock_list, list) { + + uint32_t left = kbus_lenleft(ptr); + uint32_t total; + if (ptr->read.msg) + total = + KBUS_ENTIRE_MSG_LEN(ptr->read.msg->name_len, + ptr->read.msg->data_len); + else + total = 0; + + seq_printf(s, " ksock %u last msg %u:%u " + "queue %u of %u\n", + ptr->id, ptr->last_msg_id_sent.network_id, + ptr->last_msg_id_sent.serial_num, + ptr->message_count, ptr->max_messages); + + seq_printf(s, " read byte %u of %u, " + "wrote byte %u of %s (%sfinished), " + "%ssending\n", + (total - left), total, ptr->write.pos, + kbus_msg_part_name(ptr->write.which), + ptr->write.is_finished ? "" : "not ", + ptr->sending ? "" : "not "); + + seq_printf(s, " outstanding requests %u " + "(size %u, max %u), " + "unsent replies %u (max %u)\n", + ptr->outstanding_requests.count, + ptr->outstanding_requests.size, + ptr->outstanding_requests.max_count, + ptr->num_replies_unsent, + ptr->max_replies_unsent); + } + mutex_unlock(&dev->mux); + } + + return 0; +} + +static int kbus_proc_stats_open(struct inode *inode __always_unused, + struct file *file) +{ + return single_open(file, kbus_stats_seq_show, NULL); +} + +static const struct file_operations kbus_proc_stats_file_ops = { + .owner = THIS_MODULE, + .open = kbus_proc_stats_open, + .read = seq_read, + .llseek = seq_lseek, + .release = seq_release +}; + +static struct proc_dir_entry +*kbus_create_proc_stats_file(struct proc_dir_entry *directory) +{ + struct proc_dir_entry *entry = create_proc_entry("stats", 0, directory); + if (entry) + entry->proc_fops = &kbus_proc_stats_file_ops; + return entry; +} + +/* ========================================================================= */ + +/* + * Actually setup /dev/kbus. + * + * Returns or a negative error code. + */ +static int kbus_setup_new_device(int which) +{ + struct kbus_dev *new = NULL; + dev_t this_devno; + + if (which < 0 || which > (KBUS_MAX_NUM_DEVICES - 1)) { + printk(KERN_ERR "kbus: next device index %d not %d..%d\n", + which, KBUS_MIN_NUM_DEVICES, KBUS_MAX_NUM_DEVICES); + return -EINVAL; + } + + new = kmalloc(sizeof(*new), GFP_KERNEL); + if (!new) + return -ENOMEM; + + memset(new, 0, sizeof(*new)); + + /* Connect the device up with its operations */ + this_devno = MKDEV(kbus_major, kbus_minor + which); + kbus_setup_cdev(new, this_devno); + new->index = which; + + new->verbose = KBUS_DEBUG_DEFAULT_SETTING; + + /* ================================================================= */ + /* +++ NB: before kernel 2.6.13, the functions we use were + * +++ "simple_class_create" and "simple_class_device_add". They are + * +++ documented as such in Linux Device Drivers, 3rd edition. When it + * +++ became clear that everyone was using the "simple" API, the + * +++ kernel code was refactored to make that the norm. + */ + + kbus_class_devices[which] = device_create(kbus_class_p, NULL, + this_devno, NULL, "kbus%d", which); + + kbus_devices[which] = new; + return which; +} + +static int __init kbus_init(void) +{ + int result; + int ii; + dev_t devno = 0; + + printk(KERN_NOTICE "Initialising kbus module (%d device%s)\n", + kbus_num_devices, kbus_num_devices == 1 ? "" : "s"); + if (KBUS_DEBUG_ENABLED && KBUS_DEBUG_SHOW_TRANSITIONS) + printk(KERN_NOTICE "========================\n"); + /* This allows hackers to see rmmod/insmod transitions. + * Not to be enabled by default! */ + + if (kbus_num_devices < KBUS_MIN_NUM_DEVICES || + kbus_num_devices > KBUS_MAX_NUM_DEVICES) { + printk(KERN_ERR + "kbus: requested number of devices %d not %d..%d\n", + kbus_num_devices, + KBUS_MIN_NUM_DEVICES, KBUS_MAX_NUM_DEVICES); + return -EINVAL; + } + + /* ================================================================= */ + /* + * Our main purpose is to provide /dev/kbus + * We are happy to start our device numbering with device 0 + */ + result = alloc_chrdev_region(&devno, kbus_minor, KBUS_MAX_NUM_DEVICES, + "kbus"); + /* We're quite happy with dynamic allocation of our major number */ + kbus_major = MAJOR(devno); + if (result < 0) { + printk(KERN_WARNING + "kbus: Cannot allocate character device region " + "(error %d)\n", -result); + return result; + } + + kbus_devices = kmalloc(KBUS_MAX_NUM_DEVICES * sizeof(struct kbus_dev *), + GFP_KERNEL); + if (!kbus_devices) { + printk(KERN_WARNING "kbus: Cannot allocate devices\n"); + unregister_chrdev_region(devno, kbus_num_devices); + return -ENOMEM; + } + memset(kbus_devices, 0, kbus_num_devices * sizeof(struct kbus_dev *)); + + /* ================================================================= */ + /* +++ NB: before kernel 2.6.13, the functions we use were + * +++ "simple_class_create" and "simple_class_device_add". They are + * +++ documented as such in Linux Device Drivers, 3rd edition. When it + * +++ became clear that everyone was using the "simple" API, the + * +++ kernel code was refactored to make that the norm. + */ + + /* + * To make the user's life as simple as possible, let's make our device + * hot pluggable -- this means that on a modern system it *should* just + * appear, as if by magic (and go away again when the module is + * removed). + */ + kbus_class_p = class_create(THIS_MODULE, "kbus"); + if (IS_ERR(kbus_class_p)) { + long err = PTR_ERR(kbus_class_p); + if (err == -EEXIST) { + printk(KERN_WARNING + "kbus: Cannot create kbus class, " + "it already exists\n"); + } else { + printk(KERN_ERR "kbus: Error creating kbus class\n"); + unregister_chrdev_region(devno, kbus_num_devices); + return err; + } + } + + kbus_class_devices = + kmalloc(KBUS_MAX_NUM_DEVICES * sizeof(*kbus_class_devices), + GFP_KERNEL); + if (!kbus_class_devices) { + printk(KERN_ERR + "kbus: Error creating kbus class device array\n"); + unregister_chrdev_region(devno, kbus_num_devices); + class_destroy(kbus_class_p); + return -ENOMEM; + } + + /* And connect up the number of devices we've been asked for */ + for (ii = 0; ii < kbus_num_devices; ii++) { + int res = kbus_setup_new_device(ii); + if (res < 0) { + unregister_chrdev_region(devno, kbus_num_devices); + class_destroy(kbus_class_p); + return res; + } + } + + /* ================================================================= */ + /* Within the /proc/kbus directory, we have: */ + kbus_proc_dir = proc_mkdir("kbus", NULL); + if (kbus_proc_dir) { + /* /proc/kbus/bindings -- message name bindings */ + kbus_proc_file_bindings = + kbus_create_proc_binding_file(kbus_proc_dir); + /* /proc/kbus/stats -- miscellaneous statistics */ + kbus_proc_file_stats = + kbus_create_proc_stats_file(kbus_proc_dir); + } + + return 0; +} + +static void __exit kbus_exit(void) +{ + /* No locking done, as we're standing down */ + + int ii; + dev_t devno = MKDEV(kbus_major, kbus_minor); + + printk(KERN_NOTICE "Standing down kbus module\n"); + + /* + * If I'm destroying the class, do I actually need to destroy the + * individual device therein first? Best safe... + */ + for (ii = 0; ii < kbus_num_devices; ii++) { + dev_t this_devno = MKDEV(kbus_major, kbus_minor + ii); + device_destroy(kbus_class_p, this_devno); + } + class_destroy(kbus_class_p); + + for (ii = 0; ii < kbus_num_devices; ii++) { + kbus_teardown_cdev(kbus_devices[ii]); + kfree(kbus_devices[ii]); + } + unregister_chrdev_region(devno, kbus_num_devices); + + if (kbus_proc_dir) { + if (kbus_proc_file_bindings) + remove_proc_entry("bindings", kbus_proc_dir); + if (kbus_proc_file_stats) + remove_proc_entry("stats", kbus_proc_dir); + remove_proc_entry("kbus", NULL); + } +} + +module_param(kbus_num_devices, int, S_IRUGO); +MODULE_PARM_DESC(kbus_num_devices, + "Number of KBUS device nodes to initially create"); +module_init(kbus_init); +module_exit(kbus_exit); + +MODULE_DESCRIPTION("KBUS lightweight messaging system"); +MODULE_AUTHOR("tibs@tonyibbs.co.uk, tony.ibbs@gmail.com"); +/* + * All well-behaved Linux kernel modules should be licensed under GPL v2. + * So shall it be. + * + * (According to the comments in , the "v2" is implicit here) + * + * We also license under the MPL, to allow free use outwith Linux if anyone + * wishes. + */ +MODULE_LICENSE("Dual MPL/GPL"); diff --git a/ipc/kbus_internal.h b/ipc/kbus_internal.h new file mode 100644 index 0000000..fe4cdbb --- /dev/null +++ b/ipc/kbus_internal.h @@ -0,0 +1,773 @@ +/* Kbus kernel module - internal definitions + * + * This is a character device driver, providing the messaging support + * for kbus. + * + * This header contains the definitions used internally by kbus.c. + * At the moment nothing else is expected to include this file, but + * that may change later. + * + * kbus clients should include (at least) kbus_defns.h. + */ + +/* + * ***** BEGIN LICENSE BLOCK ***** + * Version: MPL 1.1 + * + * The contents of this file are subject to the Mozilla Public License Version + * 1.1 (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * http://www.mozilla.org/MPL/ + * + * Software distributed under the License is distributed on an "AS IS" basis, + * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License + * for the specific language governing rights and limitations under the + * License. + * + * The Original Code is the KBUS Lightweight Linux-kernel mediated + * message system + * + * The Initial Developer of the Original Code is Kynesim, Cambridge UK. + * Portions created by the Initial Developer are Copyright (C) 2009 + * the Initial Developer. All Rights Reserved. + * + * Contributor(s): + * Kynesim, Cambridge UK + * Tony Ibbs + * + * Alternatively, the contents of this file may be used under the terms of the + * GNU Public License version 2 (the "GPL"), in which case the provisions of + * the GPL are applicable instead of the above. If you wish to allow the use + * of your version of this file only under the terms of the GPL and not to + * allow others to use your version of this file under the MPL, indicate your + * decision by deleting the provisions above and replace them with the notice + * and other provisions required by the GPL. If you do not delete the + * provisions above, a recipient may use your version of this file under either + * the MPL or the GPL. + * + * ***** END LICENSE BLOCK ***** + */ + +#ifndef _kbus_internal +#define _kbus_internal + +#include +#include + +#include +#include /* device classes (for hotplugging), &c */ +#include /* registering character devices */ +#include +#include /* for isalnum */ +#include +#include /* for kmalloc, etc. */ +#include /* for current->pid */ +#include /* copy_*_user() functions */ +#include /* PAGE_SIZE */ + +#include + +/* + * KBUS can support multiple devices, as /dev/kbus. These all have + * the same major device number, and map to differing minor device + * numbers. It may or may not be a surprise that just happens to be + * the minor device number as well (but don't use that information for + * anything). + * + * When KBUS starts up, it will always setup a single device (/dev/kbus0), + * but it can be asked to setup more - for instance: + * + * # insmod kbus.ko kbus_num_devices=5 + * + * There is also an IOCTL to allow user-space to request a new device as + * necessary. The hot plugging mechanisms should cause the device to appear "as + * if by magic". + * + * (This last means that we *could* default to setting up zero devices + * at module startup, and leave the user to ask for the first one, but + * that seems rather cruel.) + * + * We need to set a maximum number of KBUS devices (corresponding to a limit on + * minor device numbers). The obvious limit (corresponding to what we'd have + * got if we used the deprecated "register_chrdev" to setup our device) is 256, + * so we'll go with that. + */ +#define KBUS_MIN_NUM_DEVICES 1 + +#ifdef CONFIG_KBUS_MAX_NUM_DEVICES +#define KBUS_MAX_NUM_DEVICES CONFIG_KBUS_MAX_NUM_DEVICES +#else +#define KBUS_MAX_NUM_DEVICES 256 +#endif + +#ifndef CONFIG_KBUS_DEF_NUM_DEVICES +#define CONFIG_KBUS_DEF_NUM_DEVICES 1 +#endif + +/* Debugging setup */ + +#ifndef CONFIG_KBUS + /* ... then we're not building in-tree, + * so none of our CONFIG_* are set. + * Default sensibly. */ +#define CONFIG_KBUS_DEBUG +#endif + +#ifdef CONFIG_KBUS_DEBUG +#define KBUS_DEBUG_ENABLED 1 +#define kbus_maybe_dbg(dev, format, args...) do { \ + if (dev->verbose) \ + (void) printk(KERN_DEBUG format, ## args); \ +} while (0) +#else +#define KBUS_DEBUG_ENABLED 0 +#define kbus_maybe_dbg(dev, format, args...) ((void)0)/* no-op */ +#endif + +/* Extra debug options. These are unlikely to be of use to non-kbus-hackers + * so are not exposed as config. */ + +#define kbus_conditional_dbg(cond, dev, format, args...) do { \ + if (cond) \ + kbus_maybe_dbg(dev, format, ##args); \ +} while (0) + +#ifndef KBUS_DEBUG_READ +#define KBUS_DEBUG_READ 0 +#endif + +#define kbus_maybe_dbg_read(dev, format, args...) \ + kbus_conditional_dbg(KBUS_DEBUG_READ, dev, format, ##args) + +#ifndef KBUS_DEBUG_REFCOUNT +#define KBUS_DEBUG_REFCOUNT 0 +#endif + +/* can't quite reuse the same macro for refcount as it's called + * in functions which don't have a dev */ +#define kbus_maybe_dbg_refcount(format, args...) do { \ + (void) printk(KERN_DEBUG format, ## args); \ +} while (0) + +/* + * And even more debug for the rewrite of kbus_write() to support + * "entire" messages of any length. I suspect that this can go away + * when we've got more examples of the code working in real use. + */ +#ifndef KBUS_DEBUG_WRITE +#define KBUS_DEBUG_WRITE 0 +#endif + +#define kbus_maybe_dbg_write(dev, format, args...) \ + kbus_conditional_dbg(KBUS_DEBUG_WRITE, dev, format, ##args) + +/* Add a visual distinguisher to printk output to highlight the + * insmod/rmmod cycles of a long test run? + * This symbol should not be set to 1 unless you are running kbus + * tests, as it pollutes the printk output. */ +#ifndef KBUS_DEBUG_SHOW_TRANSITIONS +#define KBUS_DEBUG_SHOW_TRANSITIONS 0 +#endif + +/* Should we default to verbose? */ +#ifdef CONFIG_KBUS_DEBUG_DEFAULT_VERBOSE +#define KBUS_DEBUG_DEFAULT_SETTING true +#else +#define KBUS_DEBUG_DEFAULT_SETTING false +#endif + +/* Initial array sizes, could be made configurable for tuning? */ +#define KBUS_INIT_MSG_ID_MEMSIZE 16 +#define KBUS_INIT_LISTENER_ARRAY_SIZE 8 + +/* ========================================================================= */ + +/* We need a way of remembering message bindings */ +struct kbus_message_binding { + struct list_head list; + struct kbus_private_data *bound_to; /* who we're bound to */ + uint32_t bound_to_id; /* but the id is often useful */ + uint32_t is_replier; /* bound as a replier */ + uint32_t name_len; + char *name; /* the message name */ +}; + +/* + * For both keeping track of requests sent (to which we still want replies) + * and replies read (to which we haven't yet sent a reply), we need some + * means of remembering message ids. Since I'd rather not worry the rest of + * the code with how this is implemented (which is code for "I'll implement + * it very simply and worry about making it efficient/scalable later"), and + * since we always want to remember both the message ids and also how many + * there are, it seems sensible to bundle this up in its own datastructure. + */ +struct kbus_msg_id_mem { + uint32_t count; /* Number of entries in use */ + uint32_t size; /* Actual size of the array */ + uint32_t max_count; /* Max 'count' we've had */ + /* + * An array is probably the worst way to store a list of message ids, + * but it's *very simple*, and should work OK for a smallish number of + * message ids. So it's a place to start... + * + * Note the array may have "unused" slots, signified by message id {0:0} + */ + struct kbus_msg_id *ids; +}; + +/* An item in the list of requests that a Ksock has not yet replied to */ +struct kbus_unreplied_item { + struct list_head list; + struct kbus_msg_id id; /* the request's id */ + uint32_t from; /* the sender's id */ + struct kbus_name_ptr *name_ref; /* and its name... */ + uint32_t name_len; +}; + +/* + * The parts of a message being written to KBUS (via kbus_write[_parts]), + * or read by the user (via kbus_read) are: + * + * * the user-space message header - as in 'struct kbus_message_header' + * + * from which we copy various items into our own internal message header. + * + * For a "pointy" message, that is all there is. + * + * For an "entire" message, this is then followed by: + * + * * the message name + * * padding to bring that up to a NULL terminator and then a 4-byte boundary. + * + * If the "entire" message has data, then this is followed by: + * + * * N data parts (all but the last of size PART_LEN) + * * padding to bring that up to a 4-byte boundary. + * + * and finally, whether there was data or not: + * + * * the final end guard. + * + * Remember that kbus_read always delivers an "entire" message. + */ +enum kbus_msg_parts { + KBUS_PART_HDR = 0, + KBUS_PART_NAME, + KBUS_PART_NPAD, + KBUS_PART_DATA, + KBUS_PART_DPAD, + KBUS_PART_FINAL_GUARD +}; +/* N.B. New message parts require switch cases in kbus_msg_part_name() + * and kbus_write_parts(). + */ + +#define KBUS_NUM_PARTS (KBUS_PART_FINAL_GUARD+1) + +/* + * Replier typing. + * The higher the replier type, the more specific it is. + * We trust the binding mechanisms not to have created two replier + * bindings of the same type for the same name (so we shan't, for + * example, get '$.Fred.*' bound as replier twice). + */ + +enum kbus_replier_type { + UNSET = 0, + WILD_STAR, + WILD_PERCENT, + SPECIFIC +}; + +/* + * A reference counting wrapper for message data + * + * If 'as_pages' is false, then the data is stored as a single kmalloc'd + * entity, pointed to by 'parts[0]'. In this case, 'num_parts' will be 1, + * and 'last_page_len' will be the size of the allocated data. + * + * If 'as_pages' is true, then the data is stored as 'num_parts' pages, each + * pointed to by 'parts[n]'. The last page should be treated as being size + * 'last_page_len' (even if the implementation is not enforcing this). All + * other pages are of size PART_LEN. + * + * In either case, 'lengths[n]' is a "fill counter" for how many bytes of data + * are actually being stored in page 'n'. Once the data is all in place, this + * should be equal to PART_LEN or 'last_page_len' as appropriate. + * + * 'refcount' is a stanard kernel reference count for the data - when it reaches + * 0, everything (the parts, the arrays and the datastructure) gets freed. + */ +struct kbus_data_ptr { + int as_pages; + unsigned num_parts; + unsigned long *parts; + unsigned *lengths; + unsigned last_page_len; + struct kref refcount; +}; + +/* + * A reference counting wrapper for message names + * + * RATIONALE: + * + * When a message name is copied from user space, we take our first copy. + * + * In order to send a message to a Ksock, we use kbus_push_message(), which + * takes a copy of the message for each recipient. + * + * We also take a copy of the message name for our list of messages that have + * been read but not replied to. + * + * It makes sense to copy the message header, because the contents thereof are + * changed according to the particular recipient. + * + * Copying the message data (if any) is handled by the kbus_data_ptr, above, + * which provides reference counting. This makes sense because message data may + * be large. + * + * If we only have one recipient, copying the message name is not a big issue, + * but if there are many, we would prefer not to make many copies of the + * string. It is, perhaps, worth keeping a dictionary of message names. and + * referring to the name in that - but that's not an incremental change from + * the "simple copying" state we start from. + * + * The simplest change to make, which may have some benefit, is to reference + * count the names for an individual message, as is done for the message data. + * + * If we have a single recipient, we will have copied the string from user + * space, and also created the kbus_name_ptr datastructure - an overhead of 8 + * bytes. However, when we copy the message for the recipient, we do not need + * to copy the message name, so if the message name is more than 8 bytes, we + * have immediately made a gain (and experience shows that message names tend + * to be at least that long). + * + * As soon as we have more than one recipient, it becomes extremely likely that + * we have saved space, and we will definitely have saved allocations which + * could be fragmenting memory. So it sounds like a good thing to try. + * + * Also, if I later on want to store a hash code for the string (hoping to + * speed up comparisons), the new datastructure gives me somewhere to put it... + */ +struct kbus_name_ptr { + char *name; + struct kref refcount; +}; + +/* + * When the user reads a message from us, they receive a kbus_entire_message + * structure. + * + * When the user writes a message to us, they write a "pointy" message, using + * the kbus_message_header structure, or an "entire" message, using the + * kbus_entire_message structure. + * + * Within the kernel, all messages are held as "pointy" messages, but instead + * of direct pointers to the message name and data, we use reference counted + * pointers. + * + * Rather than overload the 'name' and 'data' pointer fields, with all the + * danger of getting it wrong that that implies, it seems simpler to have our + * own, internal to the kernel, clone of the datastructure, but with these + * fields defined correctly... + * + * Hmm. If we have the name and data references, perhaps we should move the + * name and data *lengths* into those same. + */ + +struct kbus_msg { + struct kbus_msg_id id; /* Unique to this message */ + struct kbus_msg_id in_reply_to; /* Which message this is a reply to */ + uint32_t to; /* 0 (empty) or a replier id */ + uint32_t from; /* 0 (KBUS) or the sender's id */ + struct kbus_orig_from orig_from; /* Cross-network linkage */ + struct kbus_orig_from final_to; /* Cross-network linkage */ + uint32_t extra; /* ignored field - future proofing */ + uint32_t flags; /* Message type/flags */ + uint32_t name_len; /* Message name's length, in bytes */ + uint32_t data_len; /* Message length, also in bytes */ + struct kbus_name_ptr *name_ref; + struct kbus_data_ptr *data_ref; +}; + +/* + * The current message that the user is reading (with kbus_read()) + * + * If 'msg' is NULL, then the data structure is "empty" (i.e., there is no + * message being read). + */ +struct kbus_read_msg { + struct kbus_entire_message user_hdr; /* the header for user space */ + + struct kbus_msg *msg; /* the internal message */ + char *parts[KBUS_NUM_PARTS]; + unsigned lengths[KBUS_NUM_PARTS]; + int which; /* The current item */ + uint32_t pos; /* How far they've read in it */ + /* + * If the current item is KBUS_PART_DATA then we 'ref_data_index' is + * which part of the data we're in, and 'pos' is how far we are through + * that particular item. + */ + uint32_t ref_data_index; +}; + +/* + * See kbus_write_parts() for how this data structure is actually used. + * + * If 'msg' is NULL, then the data structure is "empty" (i.e., there is no + * message being written). + * + * * 'is_finished' is true when we've got all the bytes for our message, + * and thus don't want any more. It's an error for the user to try to + * write more message after it is finished. + * + * For a "pointy" message, this is set immediately after the message header + * end guard is finished (the message name and any data aren't "pulled in" + * until the user does SEND). For an "entire" message, this is set after the + * final end guard is finished (so we will have the message name and any data + * in memory). + * + * * 'pointers_are_local' is true if the message's name and data have been + * transferred to kernel space (as reference counted entities), and false + * if they are (still) in user space. + * + * * 'hdr' is the message header, the shorter in-kernel version. + * + * * 'which' indicates which part of the message we think we're being given + * bytes for, from KBUS_PART_HDR through to (for an "entire" message) + * KBUS_PART_FINAL_GUARD. + * * 'pos' is the index of the next byte within the current part of whatever + * we're working on, as indicated by 'which'. Note that for message data, + * this is the index within the whole of the data (not the index within a + * data part). + * + * * If we're reading an "entire" message, then the message name gets written + * to 'ref_name', which is a reference-counted string. This is allocated to + * the correct size/shape for the entire message name, after the head has + * been read. + * + * The intention is that, if 'ref_name' is non-NULL, it should be legal + * to call 'kbus_lower_name_ref()' on it, to free its contents. + * + * * Similarly, 'ref_data' is reference-counted data, again allocated to the + * correct size/shape for the entire message data length, after the header + * has been read. The 'length' for each part is used to indicate how far + * through that part we have populated with bytes. + * + * The intention is that, if 'ref_data' is non-NULL, it should be legal + * to call 'kbus_lower_data_ref()' on it, to free its contents. + * + * 'ref_data_index' is then the index (starting at 0) of the referenced + * data part that we are populating. + */ +struct kbus_write_msg { + struct kbus_entire_message user_msg; /* from user space */ + struct kbus_msg *msg; /* our version of it */ + + uint32_t is_finished; + uint32_t pointers_are_local; + uint32_t guard; /* Whichever guard we're reading */ + char *user_name_ptr; /* User space name */ + void *user_data_ptr; /* User space data */ + enum kbus_msg_parts which; + uint32_t pos; + struct kbus_name_ptr *ref_name; + struct kbus_data_ptr *ref_data; + uint32_t ref_data_index; +}; + +/* + * The data for an unsent Replier Bind Event (in the unsent_unbind_msg_list) + * + * Note that 'binding' may theroretically be NULL (although I don't think this + * should ever actually happen). + */ +struct kbus_unsent_message_item { + struct list_head list; + struct kbus_private_data *send_to; /* who we want to send it to */ + uint32_t send_to_id; /* but the id is often useful */ + struct kbus_msg *msg; /* the message itself */ + struct kbus_message_binding *binding; /* and why we remembered it */ +}; + +/* + * This is the data for an individual Ksock + * + * Each time we open /dev/kbus, we need to remember a unique id for + * our file-instance. Using 'filp' might work, but it's not something + * we have control over, and in particular, if the file is closed and + * then reopened, there's no guarantee that a particular value of 'filp' + * won't be used again. A simple serial number is safer. + * + * Each such "opening" also has a message queue associated with it. Any + * messages this "opening" has declared itself a listener (or replier) + * for will be added to that queue. + * + * 'id' is the unique id for this file descriptor - it enables stateful message + * transtions, etc. It is local to the particular KBUS device. + * + * 'last_msg_id_sent' is the message id of the last message that was + * (successfully) written to this file descriptor. It is needed when + * constructing a reply. + * + * We have a queue of messages waiting for us to read them, in 'message_queue'. + * 'message_count' is how many messages are in the queue, and 'max_messages' + * is an indication of how many messages we shall allow in the queue. + * + * Note that, however a message was originally sent to us, messages held + * internally are always a message header plus pointers to a message name and + * (optionally) message data. See kbus_send() for details. + */ +struct kbus_private_data { + struct list_head list; + struct kbus_dev *dev; /* Which device we are on */ + uint32_t id; /* Our own id */ + struct kbus_msg_id last_msg_id_sent; /* As it says - see above */ + uint32_t message_count; /* How many messages for us */ + uint32_t max_messages; /* How many messages allowed */ + struct list_head message_queue; /* Messages for us */ + + /* + * It's useful (for /proc/kbus/bindings) to remember the PID of the + * current process + */ + pid_t pid; + + /* Wait for something to appear in the message_queue */ + wait_queue_head_t read_wait; + + /* The message currently being read by the user */ + struct kbus_read_msg read; + + /* The message currently being written by the user */ + struct kbus_write_msg write; + + /* Are we currently sending that message? */ + int sending; + + /* + * Each request we send should (eventually) generate us a reply, or + * at worst a status message from KBUS itself telling us there isn't + * going to be one. So we need to ensure that there is room in our + * (as the sender) message queue to receive all/any such. + * + * Note that this *also* allows SEND to forbid sending a Reply to a + * Request that we did not receive (or to which we have already + * replied) + */ + struct kbus_msg_id_mem outstanding_requests; + + /* + * If we are a replier for a message, then KBUS wants to ensure + * that a reply is *definitely* made. If we release ourselves, then + * we're clearly not going to reply to any requests that we have + * read but not replied to, and KBUS would like to generate a status + * message for each such. So we need a list of the information needed + * to form such Status/Reply messages. + * + * (Thus we don't need the whole of the original message, since + * we're only *really* needing its name, its id and who its + * from -- given which its easiest just to keep the parts we + * *do* need, and ignore the data.) + * + * It was decided not to place a limit on the size of this list. + * Its size is limited by the ability of sender(s) to send + * requests, which in turn is limited by the the number of slots + * they can reserve for the replies to those requests in their + * own message queues. + * + * If a limit was imposed, then we would also need to stop a sender + * sending a request because the replier has too many replies + * outstanding (for instance, because it has gone to sleep). But + * then we'd assume that it is not responding to messages in + * general, and so its message queue would fill up, and that + * should be sufficient protection. + */ + struct list_head replies_unsent; + uint32_t num_replies_unsent; + uint32_t max_replies_unsent; + + /* + * Managing which messages a replier may reply to + * ---------------------------------------------- + * We need to police replying, such that a replier may only reply + * to requests that it has received (where "received" means "had + * placed into its message queue", because KBUS must reply for us + * if the particular Ksock is not going to). + * + * It is possible to do this using either the 'outstanding_requests' + * or the 'replies_unsent' list. + * + * Using the 'outstanding_requests' list means that when a replier + * wants to send a reply, it needs to look up who the original-sender + * is (from its Ksock id, in the "from" field of the message), and + * check against that. This is a bit inefficient. + * + * Using the 'replies_unsent' list means that when a replier wants + * to send a reply, it just needs to find the right message stub + * in said 'replies_unsent' list, and check that the reply *does* + * match the original request. This may be more efficient, depending. + * + * In fact, the 'outstanding_requests' list is used, simply because + * it was implemented first. + */ + + /* + * By default, if a Ksock binds to a message name as both Replier and + * Listener (typically by binding to a specific message name as Replier + * and to a wildcard including it as Listener), and a Reqest of that + * name is sent to that Ksock, it will get the message once as Replier + * (marked "WANT_YOU_TO_REPLY"), and once as listener. + * + * This is technically sensible, but can be irritating to the end user + * who really often only wants to receive the message once. + * + * If "messages_only_once" is set, then when a message is about to be + * put onto a Ksocks message queue, it will only be added if it (i.e., + * a message with the same id) has not already just been added. This + * is safe because Requests to the specific Replier are always dealt + * with first. + * + * As a side-effect, which I think also makes sense, this will also + * mean that if a Listener has bound to the same message name multiple + * times (as a Listener), then they will only get the message once. + */ + int messages_only_once; + /* + * Messages can be added to either end of our message queue (i.e., + * depending on whether they're urgent or not). This means that the + * "only once" mechanism needs to check both ends of the queue (which + * is a pain). Or we can just remember the message id of the last + * message pushed onto the queue. Which is much simpler. + */ + struct kbus_msg_id msg_id_just_pushed; + + /* + * If this flag is set, then we may have outstanding Replier Unbound + * Event messages (kept on a list on our device). These must be read + * before any "normal" messages (on our message_queue) get read. + */ + int maybe_got_unsent_unbind_msgs; +}; + +/* What is a sensible number for the default maximum number of messages? */ +#ifndef CONFIG_KBUS_DEF_MAX_MESSAGES +#define CONFIG_KBUS_DEF_MAX_MESSAGES 100 +#endif + +/* + * What about the maximum number of unsent unbind event messages? + * This may want to be quite large, to allow for Limpets with momentary + * network outages. + * + * The default value is probably too small, but experimantation is + * needed to determine a more sensible value. + */ +#ifndef CONFIG_KBUS_MAX_UNSENT_UNBIND_MESSAGES +#define CONFIG_KBUS_MAX_UNSENT_UNBIND_MESSAGES 1000 +#endif + +/* Information belonging to each /dev/kbus device */ +struct kbus_dev { + struct cdev cdev; /* Character device data */ + + uint32_t index; /* Which /dev/kbus device we are */ + + /* + * The Big Lock + * We use a single mutex for all purposes, and all locking is done + * at the "top level", i.e., in the externally called functions. + * This simplifies the design of the internal (list processing, + * etc.) functions, at the possible cost of making interaction + * with KBUS, in general, slower. + * + * On the other hand, we favour reliable over fast. + */ + struct mutex mux; + + /* Who has bound to receive which messages in what manner */ + struct list_head bound_message_list; + + /* + * The actual Ksock entries (one per 'open("/dev/kbus")') + * This is to allow us to find the 'kbus_private_data' instances, + * so that we can get at all the message queues. The details of + * how we do this are *definitely* going to change... + */ + struct list_head open_ksock_list; + + /* Has one of our Ksocks made space available in its message queue? */ + wait_queue_head_t write_wait; + + /* + * Each open file descriptor needs an internal id - this is used + * when binding messages to listeners, but is also needed when we + * want to reply. We reserve the id 0 as a special value ("none"). + */ + uint32_t next_ksock_id; + + /* + * Every message sent has a unique id (again, unique per device). + */ + uint32_t next_msg_serial_num; + + /* Are we wanting debugging messages? */ + uint32_t verbose; + + /* + * Are we wanting to send a synthetic message for each Replier + * bind/unbind? */ + uint32_t report_replier_binds; + + /* + * If Replier (un)bind events have been requested, then when + * kbus_release is called, a message must be sent for each Replier that + * is (of necessity) unbound from the Ksock being released. For a + * normal unbound, if any of the Repliers doesn't have room in its + * message queue for such an event, then the unbind fails with -EAGAIN. + * This isn't acceptable for kbus_release (apart from anything else, + * the release might be due to the original program falling over). + * It's not acceptable to fail to send the messages (that's a general + * KBUS principle). + * + * The only sensible solution seems to be to put the messages we'd + * like to have sent onto a set-aside list, and mark each recipient + * as having messages thereon. Then, each time a Ksock looks for a + * new message, it should first check to see if it might have one + * on the set-aside list, and if it does, read that instead. + * + * Once we're doing this, though, we need some limit on how big that + * set-aside list may grow (to allow for user processes that keep + * binding and falling over!). When the list gets "too long", we set a + * "gone tragically wrong" flag, and instead of adding more unbind + * events, we instead add a single "gone tragically wrong" message for + * each Ksock. We don't revert to remembering unbind events again until + * the list has been emptied. + */ + struct list_head unsent_unbind_msg_list; + uint32_t unsent_unbind_msg_count; + int unsent_unbind_is_tragic; +}; + +/* + * Each entry in a message queue holds a single message, and a pointer to + * the message name binding that caused it to be added to the list. This + * makes it simple to remove messages from the queue if the message name + * binding is unbound. The binding shall be NULL for: + * + * * Replies + * * KBUS "synthetic" messages, which are also (essentialy) Replies + */ +struct kbus_message_queue_item { + struct list_head list; + struct kbus_msg *msg; + struct kbus_message_binding *binding; +}; + +/* The sizes of the parts in our reference counted data */ +#define KBUS_PART_LEN PAGE_SIZE +#define KBUS_PAGE_THRESHOLD (PAGE_SIZE >> 1) + +#endif /* _kbus_internal */ -- 1.7.1