[PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Since packets with invalid cmsg parameters can be rejected by kernel there
is a need to allow applications to access information on available policies
and their respective cmsg parameters at runtime. This patch simplifies
maintaining compatibility between userspace applications and DCCP code.

Signed-off-by: Tomasz Grobelny <tomasz@grobelny.oswiecenia.net>
---
 include/linux/dccp.h |    5 +++
 net/dccp/dccp.h      |    4 +++
 net/dccp/proto.c     |    2 +
 net/dccp/qpolicy.c   |   67 +++++++++++++++++++++++++++++++++++++++++++------
 4 files changed, 69 insertions(+), 9 deletions(-)

diff --git a/include/linux/dccp.h b/include/linux/dccp.h
index 5c27e27..950ecd5 100644
--- a/include/linux/dccp.h
+++ b/include/linux/dccp.h
@@ -226,6 +226,11 @@ enum dccp_packet_dequeueing_policy {
 #define DCCP_SOCKOPT_CCID_RX_INFO	128
 #define DCCP_SOCKOPT_CCID_TX_INFO	192
 
+#define DCCP_SOCKOPT_QPOLICY_MIN	256
+#define DCCP_SOCKOPT_QPOLICY_AVAILABLE	256
+#define DCCP_SOCKOPT_QPOLICY_PARAMS	257
+#define DCCP_SOCKOPT_QPOLICY_MAX	512
+
 /* maximum number of services provided on the same listening port */
 #define DCCP_SERVICE_LIST_MAX_LEN      32
 /* maximum number of CCID preferences that can be registered at one time */
diff --git a/net/dccp/dccp.h b/net/dccp/dccp.h
index c6e1a9c..1610807 100644
--- a/net/dccp/dccp.h
+++ b/net/dccp/dccp.h
@@ -223,6 +223,10 @@ extern bool		dccp_qpolicy_full(struct sock *sk);
 extern void		dccp_qpolicy_drop(struct sock *sk, struct sk_buff *skb);
 extern struct sk_buff	*dccp_qpolicy_top(struct sock *sk);
 extern struct sk_buff	*dccp_qpolicy_pop(struct sock *sk);
+extern int		dccp_qpolicy_getsockopt(struct sock *sk, int len,
+						int optname,
+						char __user *optval,
+						int __user *optlen);
 
 /*
  * TX Packet Output and TX Timers
diff --git a/net/dccp/proto.c b/net/dccp/proto.c
index bdc4126..c9596ff 100644
--- a/net/dccp/proto.c
+++ b/net/dccp/proto.c
@@ -669,6 +669,8 @@ static int do_dccp_getsockopt(struct sock *sk, int level, int optname,
 	case 192 ... 255:
 		return ccid_hc_tx_getsockopt(dp->dccps_hc_tx_ccid, sk, optname,
 					     len, (u32 __user *)optval, optlen);
+	case DCCP_SOCKOPT_QPOLICY_MIN ... DCCP_SOCKOPT_QPOLICY_MAX:
+		return dccp_qpolicy_getsockopt(sk, len, optname, optval, optlen);
 	default:
 		return -ENOPROTOOPT;
 	}
diff --git a/net/dccp/qpolicy.c b/net/dccp/qpolicy.c
index 4270c7f..ba4f6a1 100644
--- a/net/dccp/qpolicy.c
+++ b/net/dccp/qpolicy.c
@@ -9,6 +9,7 @@
  *  modify it under the terms of the GNU General Public License v2
  *  as published by the Free Software Foundation.
  */
+#include <linux/dccp.h>
 #include <asm/unaligned.h>
 #include "dccp.h"
 
@@ -64,6 +65,28 @@ static bool qpolicy_prio_full(struct sock *sk)
 	return false;
 }
 
+static int put_table(u32 *table, int psize, int len,
+				char __user *optval, int __user *optlen)
+{
+	if (len < psize)
+		return -EINVAL;
+	if (put_user(psize, optlen) || copy_to_user(optval, table, psize))
+		return -EFAULT;
+	return 0;
+}
+
+static int prio_params[] = {
+	DCCP_SCM_PRIORITY,
+};
+
+static int qpolicy_prio_getsockopt(struct sock *sk, int len, int optname,
+				char __user *optval, int __user *optlen)
+{
+	if (optname != DCCP_SOCKOPT_QPOLICY_PARAMS)
+		return -ENOPROTOOPT;
+	return put_table(prio_params, sizeof(prio_params), len, optval, optlen);
+}
+
 /**
  * struct dccp_qpolicy_operations  -  TX Packet Dequeueing Interface
  * @push: add a new @skb with possibly a struct dccp_packet_info
@@ -71,20 +94,24 @@ static bool qpolicy_prio_full(struct sock *sk)
  * @top:  peeks at whatever the queueing policy defines as its top
  */
 static struct dccp_qpolicy_operations {
-	void		(*push)	(struct sock *sk, struct sk_buff *skb);
-	bool		(*full) (struct sock *sk);
-	struct sk_buff*	(*top)  (struct sock *sk);
+	void		(*push)	     (struct sock *sk, struct sk_buff *skb);
+	bool		(*full)	     (struct sock *sk);
+	struct sk_buff*	(*top)	     (struct sock *sk);
+	int		(*getsockopt)(struct sock *sk, int len, int optname,
+				      char __user *optval, int __user *optlen);
 
 } qpol_table[DCCPQ_POLICY_MAX] = {
 	[DCCPQ_POLICY_SIMPLE] = {
-		.push = qpolicy_simple_push,
-		.full = qpolicy_simple_full,
-		.top  = qpolicy_simple_top,
+		.push		= qpolicy_simple_push,
+		.full		= qpolicy_simple_full,
+		.top		= qpolicy_simple_top,
+		.getsockopt	= NULL,
 	},
 	[DCCPQ_POLICY_PRIO] = {
-		.push = qpolicy_simple_push,
-		.full = qpolicy_prio_full,
-		.top  = qpolicy_prio_best_skb,
+		.push		= qpolicy_simple_push,
+		.full		= qpolicy_prio_full,
+		.top		= qpolicy_prio_best_skb,
+		.getsockopt	= qpolicy_prio_getsockopt,
 	},
 };
 
@@ -125,3 +152,25 @@ struct sk_buff *dccp_qpolicy_pop(struct sock *sk)
 		skb_unlink(skb, &sk->sk_write_queue);
 	return skb;
 }
+
+static int qpolicy_numbers[] = {
+	DCCPQ_POLICY_SIMPLE,
+	DCCPQ_POLICY_PRIO,
+};
+
+int dccp_qpolicy_getsockopt(struct sock *sk, int len, int optname,
+				char __user *optval, int __user *optlen)
+{
+	switch (optname) {
+	case DCCP_SOCKOPT_QPOLICY_AVAILABLE:
+		return put_table(qpolicy_numbers, sizeof(qpolicy_numbers),
+							len, optval, optlen);
+	default:
+		if ( qpol_table[dccp_sk(sk)->dccps_qpolicy].getsockopt != NULL)
+			return qpol_table[dccp_sk(sk)->dccps_qpolicy].getsockopt
+				(sk, len, optname, optval, optlen);
+		else
+			return -ENOPROTOOPT;
+	}
+	return 0;
+}
-- 
1.5.4.5

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

[-- Attachment #1: Type: text/plain, Size: 1923 bytes --]

Hi Tomasz,

| Since packets with invalid cmsg parameters can be rejected by kernel there
| is a need to allow applications to access information on available policies
| and their respective cmsg parameters at runtime. This patch simplifies
| maintaining compatibility between userspace applications and DCCP code.
| 
The difference to querying supported CCIDs is that
 * CCIDs are all defined per RFC documents, and that
 * different combinations of CCIDs are possible due to the Kconfig options.

As far as I understand your patch, querying here has a different role -
ensuring compatibilities between kernel versions.

I think it might be too early for that:
 * it takes quite a long while until patches propagate through to 
   mainline (more than half a year), so that there is the time to
   come up with a single, well-tested interface;
 * at this stage it would be better to have documentation (man pages,
   web pages, sample application code etc.) to allow people to use 
   the interface - few will want to discover the interface by grepping
   through source code.

DCCP is full of half-finished things. I would much prefer to keep this
as simple as at all possible, to have time/room to fix the missing parts
(such as no ECN support) in DCCP.

As a possible suggestion, I came up with a minimalistic variant of 
querying the interface - only 7 lines, including documentation.

This is attached and it works by exploiting that
 * policy IDs are just numbers;
 * so that we could use the highest supported ID instead of an array;
 * parameters are tied to the individual policy, so that a second
   query (about which parameters are supported) is not necessary.
   
I have put this idea as a suggestion into the `qpolicy' subtree at
	git://eden-feed.erg.abdn.ac.uk/dccp_exp

A trivial test program using this interface can be downloaded from
http://www.erg.abdn.ac.uk/users/gerrit/dccp/query_ids.tar.gz

- Gerrit

[-- Attachment #2: Combination of querying-available-policies patches. --]
[-- Type: text/x-diff, Size: 1577 bytes --]

This is a smaller diff, combined from the two patches currently in
the qpolicy subtree.
--
 Documentation/networking/dccp.txt |    3 +++
 include/linux/dccp.h              |    1 +
 net/dccp/proto.c                  |    3 +++
 3 files changed, 7 insertions(+)

--- a/Documentation/networking/dccp.txt
+++ b/Documentation/networking/dccp.txt
@@ -45,6 +45,9 @@ http://linux-net.osdl.org/index.php/DCCP
 
 Socket options
 ==============
+DCCP_SOCKOPT_QPOLICY_AVAILABLE returns the highest supported policy number. The
+policy IDs start with 0 (default policy) and are consecutively numbered.
+
 DCCP_SOCKOPT_QPOLICY_ID sets the dequeuing policy for outgoing packets. It takes
 a policy ID as argument and can only be set before the connection (i.e. changes
 during an established connection are not supported). Currently, two policies are
--- a/include/linux/dccp.h
+++ b/include/linux/dccp.h
@@ -223,6 +223,7 @@ enum dccp_packet_dequeueing_policy {
 #define DCCP_SOCKOPT_RX_CCID		15
 #define DCCP_SOCKOPT_QPOLICY_ID		16
 #define DCCP_SOCKOPT_QPOLICY_TXQLEN	17
+#define DCCP_SOCKOPT_QPOLICY_AVAILABLE	18
 #define DCCP_SOCKOPT_CCID_RX_INFO	128
 #define DCCP_SOCKOPT_CCID_TX_INFO	192
 
--- a/net/dccp/proto.c
+++ b/net/dccp/proto.c
@@ -666,6 +666,9 @@ static int do_dccp_getsockopt(struct soc
 	case DCCP_SOCKOPT_QPOLICY_TXQLEN:
 		val = dp->dccps_tx_qlen;
 		break;
+	case DCCP_SOCKOPT_QPOLICY_AVAILABLE:
+		val = DCCPQ_POLICY_MAX - 1;
+		break;
 	case 128 ... 191:
 		return ccid_hc_rx_getsockopt(dp->dccps_hc_rx_ccid, sk, optname,
 					     len, (u32 __user *)optval, optlen);

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

[-- Attachment #1: Type: text/plain, Size: 1923 bytes --]

Hi Tomasz,

| Since packets with invalid cmsg parameters can be rejected by kernel there
| is a need to allow applications to access information on available policies
| and their respective cmsg parameters at runtime. This patch simplifies
| maintaining compatibility between userspace applications and DCCP code.
| 
The difference to querying supported CCIDs is that
 * CCIDs are all defined per RFC documents, and that
 * different combinations of CCIDs are possible due to the Kconfig options.

As far as I understand your patch, querying here has a different role -
ensuring compatibilities between kernel versions.

I think it might be too early for that:
 * it takes quite a long while until patches propagate through to 
   mainline (more than half a year), so that there is the time to
   come up with a single, well-tested interface;
 * at this stage it would be better to have documentation (man pages,
   web pages, sample application code etc.) to allow people to use 
   the interface - few will want to discover the interface by grepping
   through source code.

DCCP is full of half-finished things. I would much prefer to keep this
as simple as at all possible, to have time/room to fix the missing parts
(such as no ECN support) in DCCP.

As a possible suggestion, I came up with a minimalistic variant of 
querying the interface - only 7 lines, including documentation.

This is attached and it works by exploiting that
 * policy IDs are just numbers;
 * so that we could use the highest supported ID instead of an array;
 * parameters are tied to the individual policy, so that a second
   query (about which parameters are supported) is not necessary.
   
I have put this idea as a suggestion into the `qpolicy' subtree at
	git://eden-feed.erg.abdn.ac.uk/dccp_exp

A trivial test program using this interface can be downloaded from
http://www.erg.abdn.ac.uk/users/gerrit/dccp/query_ids.tar.gz

- Gerrit

[-- Attachment #2: Combination of querying-available-policies patches. --]
[-- Type: text/x-diff, Size: 1577 bytes --]

This is a smaller diff, combined from the two patches currently in
the qpolicy subtree.
--
 Documentation/networking/dccp.txt |    3 +++
 include/linux/dccp.h              |    1 +
 net/dccp/proto.c                  |    3 +++
 3 files changed, 7 insertions(+)

--- a/Documentation/networking/dccp.txt
+++ b/Documentation/networking/dccp.txt
@@ -45,6 +45,9 @@ http://linux-net.osdl.org/index.php/DCCP
 
 Socket options
 ==============
+DCCP_SOCKOPT_QPOLICY_AVAILABLE returns the highest supported policy number. The
+policy IDs start with 0 (default policy) and are consecutively numbered.
+
 DCCP_SOCKOPT_QPOLICY_ID sets the dequeuing policy for outgoing packets. It takes
 a policy ID as argument and can only be set before the connection (i.e. changes
 during an established connection are not supported). Currently, two policies are
--- a/include/linux/dccp.h
+++ b/include/linux/dccp.h
@@ -223,6 +223,7 @@ enum dccp_packet_dequeueing_policy {
 #define DCCP_SOCKOPT_RX_CCID		15
 #define DCCP_SOCKOPT_QPOLICY_ID		16
 #define DCCP_SOCKOPT_QPOLICY_TXQLEN	17
+#define DCCP_SOCKOPT_QPOLICY_AVAILABLE	18
 #define DCCP_SOCKOPT_CCID_RX_INFO	128
 #define DCCP_SOCKOPT_CCID_TX_INFO	192
 
--- a/net/dccp/proto.c
+++ b/net/dccp/proto.c
@@ -666,6 +666,9 @@ static int do_dccp_getsockopt(struct soc
 	case DCCP_SOCKOPT_QPOLICY_TXQLEN:
 		val = dp->dccps_tx_qlen;
 		break;
+	case DCCP_SOCKOPT_QPOLICY_AVAILABLE:
+		val = DCCPQ_POLICY_MAX - 1;
+		break;
 	case 128 ... 191:
 		return ccid_hc_rx_getsockopt(dp->dccps_hc_rx_ccid, sk, optname,
 					     len, (u32 __user *)optval, optlen);

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Wednesday 21 of May 2008, Gerrit Renker napisa³:
> Hi Tomasz,
>
> | Since packets with invalid cmsg parameters can be rejected by kernel
> | there is a need to allow applications to access information on available
> | policies and their respective cmsg parameters at runtime. This patch
> | simplifies maintaining compatibility between userspace applications and
> | DCCP code.
>
> The difference to querying supported CCIDs is that
>  * CCIDs are all defined per RFC documents, and that
Yes, but does that change anything?

>  * different combinations of CCIDs are possible due to the Kconfig options.
>
Here we can have various kernel versions which is not much different. In both 
cases we need runtime feature detection.

> As far as I understand your patch, querying here has a different role -
> ensuring compatibilities between kernel versions.
>
Yes.

> I think it might be too early for that:
>  * it takes quite a long while until patches propagate through to
>    mainline (more than half a year), so that there is the time to
>    come up with a single, well-tested interface;
But when it gets into mainline people should be able to write applications 
that will be forward and backward compatible (as far as possible) with 
various kernel versions.

>  * at this stage it would be better to have documentation (man pages,
>    web pages, sample application code etc.) to allow people to use
>    the interface - few will want to discover the interface by grepping
>    through source code.
>
Sure it would be nice to have applications that use this interface. But in my 
opinion the basic interface is not yet ready to be included in mainline 
applications. It especially lacks features that will allow application 
developers to maintain compatibility.

> DCCP is full of half-finished things. 
That's why I'm trying to finish the qpolicy framework. Without providing 
runtime information it will turn out that application developers will be 
afraid to use new features just because the application won't be able to 
check if given parameter is supported or not.

> I would much prefer to keep this 
> as simple as at all possible, to have time/room to fix the missing parts
> (such as no ECN support) in DCCP.
>
I understand that there might be some missing features in DCCP that are more 
important than yet another informational getsockopt. But these features are 
IMO highly independent and can be developed in parallel.

> As a possible suggestion, I came up with a minimalistic variant of
> querying the interface - only 7 lines, including documentation.
>
> This is attached and it works by exploiting that
>  * policy IDs are just numbers;
>  * so that we could use the highest supported ID instead of an array;
I don't like the "highest supported ID" approach. But if you don't like arrays 
a simple "bool getsockopt" would do, we could just ask the kernel if it 
supports given qpolicy. Like (in pseudocode):
bool supports_prio=getsockopt(sk,DCCP_SOCKOPT_QPOLICY_AVAILABLE,QPOLICY_PRIO);
Would that be ok?

>  * parameters are tied to the individual policy, so that a second
>    query (about which parameters are supported) is not necessary.
>
Can you guarantee that nobody ever will add a parameter? In fact even today I 
can think of two parameters that could be added: the previously discussed 
timeout and my new concept - the identity or category parameter (which is a 
subject for a separate thread).

BTW, the somewhat big code was meant to act as a framework for other features. 
Like getting information about percent of dropped packets in prio qpolicy 
queue.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Wednesday 21 of May 2008, Gerrit Renker napisał:
> Hi Tomasz,
>
> | Since packets with invalid cmsg parameters can be rejected by kernel
> | there is a need to allow applications to access information on available
> | policies and their respective cmsg parameters at runtime. This patch
> | simplifies maintaining compatibility between userspace applications and
> | DCCP code.
>
> The difference to querying supported CCIDs is that
>  * CCIDs are all defined per RFC documents, and that
Yes, but does that change anything?

>  * different combinations of CCIDs are possible due to the Kconfig options.
>
Here we can have various kernel versions which is not much different. In both 
cases we need runtime feature detection.

> As far as I understand your patch, querying here has a different role -
> ensuring compatibilities between kernel versions.
>
Yes.

> I think it might be too early for that:
>  * it takes quite a long while until patches propagate through to
>    mainline (more than half a year), so that there is the time to
>    come up with a single, well-tested interface;
But when it gets into mainline people should be able to write applications 
that will be forward and backward compatible (as far as possible) with 
various kernel versions.

>  * at this stage it would be better to have documentation (man pages,
>    web pages, sample application code etc.) to allow people to use
>    the interface - few will want to discover the interface by grepping
>    through source code.
>
Sure it would be nice to have applications that use this interface. But in my 
opinion the basic interface is not yet ready to be included in mainline 
applications. It especially lacks features that will allow application 
developers to maintain compatibility.

> DCCP is full of half-finished things. 
That's why I'm trying to finish the qpolicy framework. Without providing 
runtime information it will turn out that application developers will be 
afraid to use new features just because the application won't be able to 
check if given parameter is supported or not.

> I would much prefer to keep this 
> as simple as at all possible, to have time/room to fix the missing parts
> (such as no ECN support) in DCCP.
>
I understand that there might be some missing features in DCCP that are more 
important than yet another informational getsockopt. But these features are 
IMO highly independent and can be developed in parallel.

> As a possible suggestion, I came up with a minimalistic variant of
> querying the interface - only 7 lines, including documentation.
>
> This is attached and it works by exploiting that
>  * policy IDs are just numbers;
>  * so that we could use the highest supported ID instead of an array;
I don't like the "highest supported ID" approach. But if you don't like arrays 
a simple "bool getsockopt" would do, we could just ask the kernel if it 
supports given qpolicy. Like (in pseudocode):
bool supports_prio=getsockopt(sk,DCCP_SOCKOPT_QPOLICY_AVAILABLE,QPOLICY_PRIO);
Would that be ok?

>  * parameters are tied to the individual policy, so that a second
>    query (about which parameters are supported) is not necessary.
>
Can you guarantee that nobody ever will add a parameter? In fact even today I 
can think of two parameters that could be added: the previously discussed 
timeout and my new concept - the identity or category parameter (which is a 
subject for a separate thread).

BTW, the somewhat big code was meant to act as a framework for other features. 
Like getting information about percent of dropped packets in prio qpolicy 
queue.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| But when it gets into mainline people should be able to write applications 
| that will be forward and backward compatible (as far as possible) with 
| various kernel versions.
| 
The main answer to that is below, but compare for instance with TCP -
few socket options need runtime discovery. The type of their parameters
and their option values are all described in a manpage. On the other
hand, I like your approach of trying to come up with a novel solution.

| > DCCP is full of half-finished things. 
| That's why I'm trying to finish the qpolicy framework. Without providing 
| runtime information it will turn out that application developers will be 
| afraid to use new features just because the application won't be able to 
| check if given parameter is supported or not.
| 
And you have done a good job so far, it is a very useful addition.


| > I would much prefer to keep this 
| > as simple as at all possible, to have time/room to fix the missing parts
| > (such as no ECN support) in DCCP.
| >
| I understand that there might be some missing features in DCCP that are more 
| important than yet another informational getsockopt. But these features are 
| IMO highly independent and can be developed in parallel.
| 
Agreed.

| > As a possible suggestion, I came up with a minimalistic variant of
| > querying the interface - only 7 lines, including documentation.
| >
| > This is attached and it works by exploiting that
| >  * policy IDs are just numbers;
| >  * so that we could use the highest supported ID instead of an array;
| I don't like the "highest supported ID" approach. But if you don't like arrays 
| a simple "bool getsockopt" would do, we could just ask the kernel if it 
| supports given qpolicy. Like (in pseudocode):
| bool supports_prio=getsockopt(sk,DCCP_SOCKOPT_QPOLICY_AVAILABLE,QPOLICY_PRIO);
| Would that be ok?
| 
What I sent is just a sketch, nothing set in stone. I am happy to take
my patch out of the repository if there are better solutions.


| >  * parameters are tied to the individual policy, so that a second
| >    query (about which parameters are supported) is not necessary.
| >
| Can you guarantee that nobody ever will add a parameter? In fact even today I 
| can think of two parameters that could be added: the previously discussed 
| timeout and my new concept - the identity or category parameter (which is a 
| subject for a separate thread).
| 
During the design phase it is almost certain to change several times.

When the design phase is over, it will have some parts that will not
likely change.

Hence I am trying to figure out - how much change is due to re-designing
things and how much change is de facto required for a useful dynamic
interface?

| BTW, the somewhat big code was meant to act as a framework for other features. 
| Like getting information about percent of dropped packets in prio qpolicy 
| queue.
| -- 
Ah - didn't understand what the qpolicy-specific getsockopt hooks were for.

I think there is a way of doing this, but it requires a bit more work. 
This would be to use netlink sockets to communicate/request/poll information. 

The two alternatives I am aware of are

 * kernel/userspace connector
   [ Documentation/connector/connector.txt ]
 * generic netlink interface
   http://www.linux-foundation.org/en/Net:Generic_Netlink_HOWTO

If done well, the interface could be very useful for several other
things in DCCP:
 * querying qpolicy interface (with regard to this email thread)	
 * querying the CCIDs (available, set preference list)
 * getting much-needed runtime statistics into user-space
   - this is a feature missing in UDP (and partly also TCP)
   - so far only via CCID-3 getsockopt (tx_info/rx_info)
   - there is research which says it would be nice to have the
     current RTT, loss statistics etc in user-space
 * thus calling for a generic solution.

What do you think about this alternative?

- Gerrit

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

| But when it gets into mainline people should be able to write applications 
| that will be forward and backward compatible (as far as possible) with 
| various kernel versions.
| 
The main answer to that is below, but compare for instance with TCP -
few socket options need runtime discovery. The type of their parameters
and their option values are all described in a manpage. On the other
hand, I like your approach of trying to come up with a novel solution.

| > DCCP is full of half-finished things. 
| That's why I'm trying to finish the qpolicy framework. Without providing 
| runtime information it will turn out that application developers will be 
| afraid to use new features just because the application won't be able to 
| check if given parameter is supported or not.
| 
And you have done a good job so far, it is a very useful addition.


| > I would much prefer to keep this 
| > as simple as at all possible, to have time/room to fix the missing parts
| > (such as no ECN support) in DCCP.
| >
| I understand that there might be some missing features in DCCP that are more 
| important than yet another informational getsockopt. But these features are 
| IMO highly independent and can be developed in parallel.
| 
Agreed.

| > As a possible suggestion, I came up with a minimalistic variant of
| > querying the interface - only 7 lines, including documentation.
| >
| > This is attached and it works by exploiting that
| >  * policy IDs are just numbers;
| >  * so that we could use the highest supported ID instead of an array;
| I don't like the "highest supported ID" approach. But if you don't like arrays 
| a simple "bool getsockopt" would do, we could just ask the kernel if it 
| supports given qpolicy. Like (in pseudocode):
| bool supports_prio=getsockopt(sk,DCCP_SOCKOPT_QPOLICY_AVAILABLE,QPOLICY_PRIO);
| Would that be ok?
| 
What I sent is just a sketch, nothing set in stone. I am happy to take
my patch out of the repository if there are better solutions.


| >  * parameters are tied to the individual policy, so that a second
| >    query (about which parameters are supported) is not necessary.
| >
| Can you guarantee that nobody ever will add a parameter? In fact even today I 
| can think of two parameters that could be added: the previously discussed 
| timeout and my new concept - the identity or category parameter (which is a 
| subject for a separate thread).
| 
During the design phase it is almost certain to change several times.

When the design phase is over, it will have some parts that will not
likely change.

Hence I am trying to figure out - how much change is due to re-designing
things and how much change is de facto required for a useful dynamic
interface?

| BTW, the somewhat big code was meant to act as a framework for other features. 
| Like getting information about percent of dropped packets in prio qpolicy 
| queue.
| -- 
Ah - didn't understand what the qpolicy-specific getsockopt hooks were for.

I think there is a way of doing this, but it requires a bit more work. 
This would be to use netlink sockets to communicate/request/poll information. 

The two alternatives I am aware of are

 * kernel/userspace connector
   [ Documentation/connector/connector.txt ]
 * generic netlink interface
   http://www.linux-foundation.org/en/Net:Generic_Netlink_HOWTO

If done well, the interface could be very useful for several other
things in DCCP:
 * querying qpolicy interface (with regard to this email thread)	
 * querying the CCIDs (available, set preference list)
 * getting much-needed runtime statistics into user-space
   - this is a feature missing in UDP (and partly also TCP)
   - so far only via CCID-3 getsockopt (tx_info/rx_info)
   - there is research which says it would be nice to have the
     current RTT, loss statistics etc in user-space
 * thus calling for a generic solution.

What do you think about this alternative?

- Gerrit

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Thursday 22 of May 2008, Gerrit Renker napisa³:
> | But when it gets into mainline people should be able to write
> | applications that will be forward and backward compatible (as far as
> | possible) with various kernel versions.
>
> The main answer to that is below, but compare for instance with TCP -
> few socket options need runtime discovery. The type of their parameters
> and their option values are all described in a manpage. On the other
> hand, I like your approach of trying to come up with a novel solution.
>
TCP was designed before the era of having everything pluggable. DCCP on the 
other hand is prepared for adding new CCIDs. Logically then, it should be 
extensible in other areas too.

> | > As a possible suggestion, I came up with a minimalistic variant of
> | > querying the interface - only 7 lines, including documentation.
> | >
> | > This is attached and it works by exploiting that
> | >  * policy IDs are just numbers;
> | >  * so that we could use the highest supported ID instead of an array;
> |
> | I don't like the "highest supported ID" approach. But if you don't like
> | arrays a simple "bool getsockopt" would do, we could just ask the kernel
> | if it supports given qpolicy. Like (in pseudocode):
> | bool
> | supports_prio=getsockopt(sk,DCCP_SOCKOPT_QPOLICY_AVAILABLE,QPOLICY_PRIO);
> | Would that be ok?
>
> What I sent is just a sketch, nothing set in stone. I am happy to take
> my patch out of the repository if there are better solutions.
>
The question is: would you consider such a solution better? 

> | >  * parameters are tied to the individual policy, so that a second
> | >    query (about which parameters are supported) is not necessary.
> |
> | Can you guarantee that nobody ever will add a parameter? In fact even
> | today I can think of two parameters that could be added: the previously
> | discussed timeout and my new concept - the identity or category parameter
> | (which is a subject for a separate thread).
>
> During the design phase it is almost certain to change several times.
>
> When the design phase is over, it will have some parts that will not
> likely change.
>
> Hence I am trying to figure out - how much change is due to re-designing
> things and how much change is de facto required for a useful dynamic
> interface?
>
IMO we could divide the interface into two parts:
 - operations - they are likely to stabilize before pushing the code to 
mainline,
 - parameters (all kinds of numbers like DCCP_SCM_xxx, qpolicy ids, etc.) - 
there should always be a room for new ones (and maybe even deleting old 
ones). And one should be able to verify which numbers are valid - that's why 
we need operations for this purpose that are available from the very 
beginning.

> | BTW, the somewhat big code was meant to act as a framework for other
> | features. Like getting information about percent of dropped packets in
> | prio qpolicy queue.
> | --
>
> Ah - didn't understand what the qpolicy-specific getsockopt hooks were for.
>
> I think there is a way of doing this, but it requires a bit more work.
> This would be to use netlink sockets to communicate/request/poll
> information.
>
> The two alternatives I am aware of are
>
>  * kernel/userspace connector
>    [ Documentation/connector/connector.txt ]
>  * generic netlink interface
>    http://www.linux-foundation.org/en/Net:Generic_Netlink_HOWTO
>
As far as I understand netlink is a kind of intermodule communication 
mechanism (where module may be either in-kernel or userspace application).

> If done well, the interface could be very useful for several other
> things in DCCP:
>  * querying qpolicy interface (with regard to this email thread)
>  * querying the CCIDs (available, set preference list)
>  * getting much-needed runtime statistics into user-space
>    - this is a feature missing in UDP (and partly also TCP)
>    - so far only via CCID-3 getsockopt (tx_info/rx_info)
>    - there is research which says it would be nice to have the
>      current RTT, loss statistics etc in user-space
>  * thus calling for a generic solution.
>
> What do you think about this alternative?
>
I have nothing against creating generic interface for obtaining information 
about various aspects of dccp. But I can't see how netlink can help us here. 
From the documents I've read I understand that generic netlink requires you 
to create a special kind of socket type and then you can send or receive 
information through it. But it seems to be something separate from dccp 
sockets.

As for information we can get from kernel wrt dccp we have at least:
1. fixed information that depends only on kernel version. For example list of 
ccids, list of available qpolicies, list of parameters for given qpolicy, 
etc. These are system wide and don't need reference to socket. These could 
even be exposed by read-only entries in /sys or /proc.
2. typical socket options. Among others: currently used rx/tx ccid, currently 
used qpolicy, queue and buffer sizes, etc. For these we need reference to 
socket and get/setsockopts are the natural choice. And I guess no changes 
should happen here.
3. statistics. These are not options in the sense that you cannot set them. 
You also cannot expect that two consecutive reads will return the same value. 
They depend on certain asynchronous events in various parts of dccp code. The 
first question is: should we pass those raw events to applications (such 
as "prio qpolicy: packet dropped") or aggregate data ("in the last 100 
packets 17 were dropped before sending")? For this kind of information we 
need reference to socket (struct sock *). And I can't see how we could obtain 
it from functions not mentioned in struct proto.

I suggest that we discuss points 1 and 3 separately because it may turn that 
different mechanisms will be applicable. getsockopt is possible in both which 
doesn't mean that it is the best solution.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Thursday 22 of May 2008, Gerrit Renker napisał:
> | But when it gets into mainline people should be able to write
> | applications that will be forward and backward compatible (as far as
> | possible) with various kernel versions.
>
> The main answer to that is below, but compare for instance with TCP -
> few socket options need runtime discovery. The type of their parameters
> and their option values are all described in a manpage. On the other
> hand, I like your approach of trying to come up with a novel solution.
>
TCP was designed before the era of having everything pluggable. DCCP on the 
other hand is prepared for adding new CCIDs. Logically then, it should be 
extensible in other areas too.

> | > As a possible suggestion, I came up with a minimalistic variant of
> | > querying the interface - only 7 lines, including documentation.
> | >
> | > This is attached and it works by exploiting that
> | >  * policy IDs are just numbers;
> | >  * so that we could use the highest supported ID instead of an array;
> |
> | I don't like the "highest supported ID" approach. But if you don't like
> | arrays a simple "bool getsockopt" would do, we could just ask the kernel
> | if it supports given qpolicy. Like (in pseudocode):
> | bool
> | supports_prio=getsockopt(sk,DCCP_SOCKOPT_QPOLICY_AVAILABLE,QPOLICY_PRIO);
> | Would that be ok?
>
> What I sent is just a sketch, nothing set in stone. I am happy to take
> my patch out of the repository if there are better solutions.
>
The question is: would you consider such a solution better? 

> | >  * parameters are tied to the individual policy, so that a second
> | >    query (about which parameters are supported) is not necessary.
> |
> | Can you guarantee that nobody ever will add a parameter? In fact even
> | today I can think of two parameters that could be added: the previously
> | discussed timeout and my new concept - the identity or category parameter
> | (which is a subject for a separate thread).
>
> During the design phase it is almost certain to change several times.
>
> When the design phase is over, it will have some parts that will not
> likely change.
>
> Hence I am trying to figure out - how much change is due to re-designing
> things and how much change is de facto required for a useful dynamic
> interface?
>
IMO we could divide the interface into two parts:
 - operations - they are likely to stabilize before pushing the code to 
mainline,
 - parameters (all kinds of numbers like DCCP_SCM_xxx, qpolicy ids, etc.) - 
there should always be a room for new ones (and maybe even deleting old 
ones). And one should be able to verify which numbers are valid - that's why 
we need operations for this purpose that are available from the very 
beginning.

> | BTW, the somewhat big code was meant to act as a framework for other
> | features. Like getting information about percent of dropped packets in
> | prio qpolicy queue.
> | --
>
> Ah - didn't understand what the qpolicy-specific getsockopt hooks were for.
>
> I think there is a way of doing this, but it requires a bit more work.
> This would be to use netlink sockets to communicate/request/poll
> information.
>
> The two alternatives I am aware of are
>
>  * kernel/userspace connector
>    [ Documentation/connector/connector.txt ]
>  * generic netlink interface
>    http://www.linux-foundation.org/en/Net:Generic_Netlink_HOWTO
>
As far as I understand netlink is a kind of intermodule communication 
mechanism (where module may be either in-kernel or userspace application).

> If done well, the interface could be very useful for several other
> things in DCCP:
>  * querying qpolicy interface (with regard to this email thread)
>  * querying the CCIDs (available, set preference list)
>  * getting much-needed runtime statistics into user-space
>    - this is a feature missing in UDP (and partly also TCP)
>    - so far only via CCID-3 getsockopt (tx_info/rx_info)
>    - there is research which says it would be nice to have the
>      current RTT, loss statistics etc in user-space
>  * thus calling for a generic solution.
>
> What do you think about this alternative?
>
I have nothing against creating generic interface for obtaining information 
about various aspects of dccp. But I can't see how netlink can help us here. 
From the documents I've read I understand that generic netlink requires you 
to create a special kind of socket type and then you can send or receive 
information through it. But it seems to be something separate from dccp 
sockets.

As for information we can get from kernel wrt dccp we have at least:
1. fixed information that depends only on kernel version. For example list of 
ccids, list of available qpolicies, list of parameters for given qpolicy, 
etc. These are system wide and don't need reference to socket. These could 
even be exposed by read-only entries in /sys or /proc.
2. typical socket options. Among others: currently used rx/tx ccid, currently 
used qpolicy, queue and buffer sizes, etc. For these we need reference to 
socket and get/setsockopts are the natural choice. And I guess no changes 
should happen here.
3. statistics. These are not options in the sense that you cannot set them. 
You also cannot expect that two consecutive reads will return the same value. 
They depend on certain asynchronous events in various parts of dccp code. The 
first question is: should we pass those raw events to applications (such 
as "prio qpolicy: packet dropped") or aggregate data ("in the last 100 
packets 17 were dropped before sending")? For this kind of information we 
need reference to socket (struct sock *). And I can't see how we could obtain 
it from functions not mentioned in struct proto.

I suggest that we discuss points 1 and 3 separately because it may turn that 
different mechanisms will be applicable. getsockopt is possible in both which 
doesn't mean that it is the best solution.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| > | I don't like the "highest supported ID" approach. But if you don't like
| > | arrays a simple "bool getsockopt" would do, we could just ask the kernel
| > | if it supports given qpolicy. Like (in pseudocode):
| > | bool
| > | supports_prio=getsockopt(sk,DCCP_SOCKOPT_QPOLICY_AVAILABLE,QPOLICY_PRIO);
| > | Would that be ok?
| >
| > What I sent is just a sketch, nothing set in stone. I am happy to take
| > my patch out of the repository if there are better solutions.
| >
| The question is: would you consider such a solution better? 
| 
I think it is too early for this question, it needs some practical experience.
It may be that a third or fourth solution proves more useful.


| > Hence I am trying to figure out - how much change is due to re-designing
| > things and how much change is de facto required for a useful dynamic
| > interface?
| >
| IMO we could divide the interface into two parts:
|  - operations - they are likely to stabilize before pushing the code to 
| mainline,
|  - parameters (all kinds of numbers like DCCP_SCM_xxx, qpolicy ids, etc.) - 
| there should always be a room for new ones (and maybe even deleting old 
| ones). And one should be able to verify which numbers are valid - that's why 
| we need operations for this purpose that are available from the very 
| beginning.
| 
I think this problem appears in other kernel areas as well, such as
finding consistent identifiers for identifiers, flags, symbolic names.

Haven't grepped through, but there is likely a smart solution available
already somewhere. 

For IETF specifications, the IANA handles all numbers that appear in
packets, a similar thing appears here. But with some discipline it
should not cause a problem. 


| I have nothing against creating generic interface for obtaining information 
| about various aspects of dccp. But I can't see how netlink can help us here. 
| From the documents I've read I understand that generic netlink requires you 
| to create a special kind of socket type and then you can send or receive 
| information through it. But it seems to be something separate from dccp 
| sockets.
| 
Yes, the netlink socket would be different from the DCCP socket and it
is actually a good point - it shows that this interface can only be used
for global parameters or settings. Or maybe there is a way of
associating both sockets.


| As for information we can get from kernel wrt dccp we have at least:
| 1. fixed information that depends only on kernel version. For example list of 
| ccids, list of available qpolicies, list of parameters for given qpolicy, 
| etc. These are system wide and don't need reference to socket. These could 
| even be exposed by read-only entries in /sys or /proc.
That is a good point - I think Arnaldo had a similar idea once for implenting
system-wide policies regarding which CCIDs are supported. Something like
net.ipv4.tcp_available_congestion_control.

| 2. typical socket options. Among others: currently used rx/tx ccid, currently 
| used qpolicy, queue and buffer sizes, etc. For these we need reference to 
| socket and get/setsockopts are the natural choice. And I guess no changes 
| should happen here.
Agree.

| 3. statistics. These are not options in the sense that you cannot set them. 
| You also cannot expect that two consecutive reads will return the same value. 
| They depend on certain asynchronous events in various parts of dccp code. The 
| first question is: should we pass those raw events to applications (such 
| as "prio qpolicy: packet dropped") or aggregate data ("in the last 100 
| packets 17 were dropped before sending")? For this kind of information we 
| need reference to socket (struct sock *). And I can't see how we could obtain 
| it from functions not mentioned in struct proto.
| 
It was for this part that I looked at netlink. This goes into the
direction of a new API or at least API extensions.

For global statistics there is already the DCCP MIB, but it needs some
more work (in /proc/snmp there are no entries at the moment), a ToDo.

For per-socket statistics there is indeed a need for a notification
mechanism. If a synchronous mechanism is sufficient, then something like
the current CCID-3 getsockopt(DCCP_SOCKOPT_CCID_{RX,TX}_INFO) can be used.

For asynchronous notification, using a special signal comes to mind,
where the application installs a signal handler as notifier.

The best that I can think of is to map a segment of userspace memory
into the kernel and use this memory area as a (ready-only) statistics
struct. That would save the system call overhead of using getsockopt().

That is my list of ideas at the moment. Probably not exhaustive.

- Gerrit

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

| > | I don't like the "highest supported ID" approach. But if you don't like
| > | arrays a simple "bool getsockopt" would do, we could just ask the kernel
| > | if it supports given qpolicy. Like (in pseudocode):
| > | bool
| > | supports_prio=getsockopt(sk,DCCP_SOCKOPT_QPOLICY_AVAILABLE,QPOLICY_PRIO);
| > | Would that be ok?
| >
| > What I sent is just a sketch, nothing set in stone. I am happy to take
| > my patch out of the repository if there are better solutions.
| >
| The question is: would you consider such a solution better? 
| 
I think it is too early for this question, it needs some practical experience.
It may be that a third or fourth solution proves more useful.


| > Hence I am trying to figure out - how much change is due to re-designing
| > things and how much change is de facto required for a useful dynamic
| > interface?
| >
| IMO we could divide the interface into two parts:
|  - operations - they are likely to stabilize before pushing the code to 
| mainline,
|  - parameters (all kinds of numbers like DCCP_SCM_xxx, qpolicy ids, etc.) - 
| there should always be a room for new ones (and maybe even deleting old 
| ones). And one should be able to verify which numbers are valid - that's why 
| we need operations for this purpose that are available from the very 
| beginning.
| 
I think this problem appears in other kernel areas as well, such as
finding consistent identifiers for identifiers, flags, symbolic names.

Haven't grepped through, but there is likely a smart solution available
already somewhere. 

For IETF specifications, the IANA handles all numbers that appear in
packets, a similar thing appears here. But with some discipline it
should not cause a problem. 


| I have nothing against creating generic interface for obtaining information 
| about various aspects of dccp. But I can't see how netlink can help us here. 
| From the documents I've read I understand that generic netlink requires you 
| to create a special kind of socket type and then you can send or receive 
| information through it. But it seems to be something separate from dccp 
| sockets.
| 
Yes, the netlink socket would be different from the DCCP socket and it
is actually a good point - it shows that this interface can only be used
for global parameters or settings. Or maybe there is a way of
associating both sockets.


| As for information we can get from kernel wrt dccp we have at least:
| 1. fixed information that depends only on kernel version. For example list of 
| ccids, list of available qpolicies, list of parameters for given qpolicy, 
| etc. These are system wide and don't need reference to socket. These could 
| even be exposed by read-only entries in /sys or /proc.
That is a good point - I think Arnaldo had a similar idea once for implenting
system-wide policies regarding which CCIDs are supported. Something like
net.ipv4.tcp_available_congestion_control.

| 2. typical socket options. Among others: currently used rx/tx ccid, currently 
| used qpolicy, queue and buffer sizes, etc. For these we need reference to 
| socket and get/setsockopts are the natural choice. And I guess no changes 
| should happen here.
Agree.

| 3. statistics. These are not options in the sense that you cannot set them. 
| You also cannot expect that two consecutive reads will return the same value. 
| They depend on certain asynchronous events in various parts of dccp code. The 
| first question is: should we pass those raw events to applications (such 
| as "prio qpolicy: packet dropped") or aggregate data ("in the last 100 
| packets 17 were dropped before sending")? For this kind of information we 
| need reference to socket (struct sock *). And I can't see how we could obtain 
| it from functions not mentioned in struct proto.
| 
It was for this part that I looked at netlink. This goes into the
direction of a new API or at least API extensions.

For global statistics there is already the DCCP MIB, but it needs some
more work (in /proc/snmp there are no entries at the moment), a ToDo.

For per-socket statistics there is indeed a need for a notification
mechanism. If a synchronous mechanism is sufficient, then something like
the current CCID-3 getsockopt(DCCP_SOCKOPT_CCID_{RX,TX}_INFO) can be used.

For asynchronous notification, using a special signal comes to mind,
where the application installs a signal handler as notifier.

The best that I can think of is to map a segment of userspace memory
into the kernel and use this memory area as a (ready-only) statistics
struct. That would save the system call overhead of using getsockopt().

That is my list of ideas at the moment. Probably not exhaustive.

- Gerrit

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Monday 26 of May 2008, Gerrit Renker napisa³:
> | I have nothing against creating generic interface for obtaining
> | information about various aspects of dccp. But I can't see how netlink
> | can help us here. From the documents I've read I understand that generic
> | netlink requires you to create a special kind of socket type and then you
> | can send or receive information through it. But it seems to be something
> | separate from dccp sockets.
>
> Yes, the netlink socket would be different from the DCCP socket and it
> is actually a good point - it shows that this interface can only be used
> for global parameters or settings. Or maybe there is a way of
> associating both sockets.
>
I haven't seen any. But I'm quite new to kernel development (and to netlink in 
particular).

> | As for information we can get from kernel wrt dccp we have at least:
> | 1. fixed information that depends only on kernel version. For example
> | list of ccids, list of available qpolicies, list of parameters for given
> | qpolicy, etc. These are system wide and don't need reference to socket.
> | These could even be exposed by read-only entries in /sys or /proc.
>
> That is a good point - I think Arnaldo had a similar idea once for
> implenting system-wide policies regarding which CCIDs are supported.
> Something like net.ipv4.tcp_available_congestion_control.
>
Ok, we may go this way. I'll try to write a patch in a few days (quite busy 
now).

> | 3. statistics. These are not options in the sense that you cannot set
> | them. You also cannot expect that two consecutive reads will return the
> | same value. They depend on certain asynchronous events in various parts
> | of dccp code. The first question is: should we pass those raw events to
> | applications (such as "prio qpolicy: packet dropped") or aggregate data
> | ("in the last 100 packets 17 were dropped before sending")? For this kind
> | of information we need reference to socket (struct sock *). And I can't
> | see how we could obtain it from functions not mentioned in struct proto.
>
> It was for this part that I looked at netlink. This goes into the
> direction of a new API or at least API extensions.
> 
We basically need a callback from code that can access struct sock...

> (...)
> For per-socket statistics there is indeed a need for a notification
> mechanism. If a synchronous mechanism is sufficient, then something like
> the current CCID-3 getsockopt(DCCP_SOCKOPT_CCID_{RX,TX}_INFO) can be used.
>
Synchronous mechanism is acceptable but callback (at least as an option) would 
be way nicer.

> For asynchronous notification, using a special signal comes to mind,
> where the application installs a signal handler as notifier.
>
We'd have to pass affected socket identifier (process may use more than one 
socket). To me it looks like a not-so-nice hack. But still I don't have 
better ideas on how to implement asynchronous event notification (callback). 
Ok, but if we are at hackish ideas what about this one: use dccp_ioctl to 
wait on a mutex. If an event occurs we release mutex thus allowing dccp_ioctl 
to finish execution and consequently informing user that something 
interesting has just happened - what it exactly is would have to be 
determined by other means.

> The best that I can think of is to map a segment of userspace memory
> into the kernel and use this memory area as a (ready-only) statistics
> struct. That would save the system call overhead of using getsockopt().
>
I don't think the syscall overhead is big enough to care. After all you don't 
need statistics that often. Shared memory creates potential problems with 
synchronization (ok, it is read-only but you need to provide consistent 
data). Plus you must update them whether needed or not because you never know 
when the user will want to read them (it may be a problem in some scenarios 
and may not be a problem in others). IMO more problems that it's worth.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Monday 26 of May 2008, Gerrit Renker napisał:
> | I have nothing against creating generic interface for obtaining
> | information about various aspects of dccp. But I can't see how netlink
> | can help us here. From the documents I've read I understand that generic
> | netlink requires you to create a special kind of socket type and then you
> | can send or receive information through it. But it seems to be something
> | separate from dccp sockets.
>
> Yes, the netlink socket would be different from the DCCP socket and it
> is actually a good point - it shows that this interface can only be used
> for global parameters or settings. Or maybe there is a way of
> associating both sockets.
>
I haven't seen any. But I'm quite new to kernel development (and to netlink in 
particular).

> | As for information we can get from kernel wrt dccp we have at least:
> | 1. fixed information that depends only on kernel version. For example
> | list of ccids, list of available qpolicies, list of parameters for given
> | qpolicy, etc. These are system wide and don't need reference to socket.
> | These could even be exposed by read-only entries in /sys or /proc.
>
> That is a good point - I think Arnaldo had a similar idea once for
> implenting system-wide policies regarding which CCIDs are supported.
> Something like net.ipv4.tcp_available_congestion_control.
>
Ok, we may go this way. I'll try to write a patch in a few days (quite busy 
now).

> | 3. statistics. These are not options in the sense that you cannot set
> | them. You also cannot expect that two consecutive reads will return the
> | same value. They depend on certain asynchronous events in various parts
> | of dccp code. The first question is: should we pass those raw events to
> | applications (such as "prio qpolicy: packet dropped") or aggregate data
> | ("in the last 100 packets 17 were dropped before sending")? For this kind
> | of information we need reference to socket (struct sock *). And I can't
> | see how we could obtain it from functions not mentioned in struct proto.
>
> It was for this part that I looked at netlink. This goes into the
> direction of a new API or at least API extensions.
> 
We basically need a callback from code that can access struct sock...

> (...)
> For per-socket statistics there is indeed a need for a notification
> mechanism. If a synchronous mechanism is sufficient, then something like
> the current CCID-3 getsockopt(DCCP_SOCKOPT_CCID_{RX,TX}_INFO) can be used.
>
Synchronous mechanism is acceptable but callback (at least as an option) would 
be way nicer.

> For asynchronous notification, using a special signal comes to mind,
> where the application installs a signal handler as notifier.
>
We'd have to pass affected socket identifier (process may use more than one 
socket). To me it looks like a not-so-nice hack. But still I don't have 
better ideas on how to implement asynchronous event notification (callback). 
Ok, but if we are at hackish ideas what about this one: use dccp_ioctl to 
wait on a mutex. If an event occurs we release mutex thus allowing dccp_ioctl 
to finish execution and consequently informing user that something 
interesting has just happened - what it exactly is would have to be 
determined by other means.

> The best that I can think of is to map a segment of userspace memory
> into the kernel and use this memory area as a (ready-only) statistics
> struct. That would save the system call overhead of using getsockopt().
>
I don't think the syscall overhead is big enough to care. After all you don't 
need statistics that often. Shared memory creates potential problems with 
synchronization (ok, it is read-only but you need to provide consistent 
data). Plus you must update them whether needed or not because you never know 
when the user will want to read them (it may be a problem in some scenarios 
and may not be a problem in others). IMO more problems that it's worth.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Monday 26 of May 2008, napisa³e¶:
> Dnia Monday 26 of May 2008, Gerrit Renker napisa³:
> > | As for information we can get from kernel wrt dccp we have at least:
> > | 1. fixed information that depends only on kernel version. For example
> > | list of ccids, list of available qpolicies, list of parameters for
> > | given qpolicy, etc. These are system wide and don't need reference to
> > | socket. These could even be exposed by read-only entries in /sys or
> > | /proc.
> >
> > That is a good point - I think Arnaldo had a similar idea once for
> > implenting system-wide policies regarding which CCIDs are supported.
> > Something like net.ipv4.tcp_available_congestion_control.
>
> Ok, we may go this way. I'll try to write a patch in a few days (quite busy
> now).
>
Now that I had a closer look at implementing this functionality I have a few 
questions:
1. Where should information about available qpolicies and their parametrs be 
exported? Would /proc/net/dccp/qpolicies/ be a good choice?
2. I guess we should have at least one file per qpolicy with parameters listed 
inside. Like that:
/proc/.../qpolicies/simple: <empty>
/proc/.../qpolicies/prio: 1 (DCCP_SCM_PRIORITY) 2 (DCCP_SCM_TIMEOUT)
But we could also have qpolicy represented by directory and parameters by 
files:
/proc/.../qpolicies/simple/
/proc/.../qpolicies/prio/
/proc/.../qpolicies/prio/priority: <empty>
/proc/.../qpolicies/prio/timeout: <empty>
Which layout do you find better?
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Monday 26 of May 2008, napisałeś:
> Dnia Monday 26 of May 2008, Gerrit Renker napisał:
> > | As for information we can get from kernel wrt dccp we have at least:
> > | 1. fixed information that depends only on kernel version. For example
> > | list of ccids, list of available qpolicies, list of parameters for
> > | given qpolicy, etc. These are system wide and don't need reference to
> > | socket. These could even be exposed by read-only entries in /sys or
> > | /proc.
> >
> > That is a good point - I think Arnaldo had a similar idea once for
> > implenting system-wide policies regarding which CCIDs are supported.
> > Something like net.ipv4.tcp_available_congestion_control.
>
> Ok, we may go this way. I'll try to write a patch in a few days (quite busy
> now).
>
Now that I had a closer look at implementing this functionality I have a few 
questions:
1. Where should information about available qpolicies and their parametrs be 
exported? Would /proc/net/dccp/qpolicies/ be a good choice?
2. I guess we should have at least one file per qpolicy with parameters listed 
inside. Like that:
/proc/.../qpolicies/simple: <empty>
/proc/.../qpolicies/prio: 1 (DCCP_SCM_PRIORITY) 2 (DCCP_SCM_TIMEOUT)
But we could also have qpolicy represented by directory and parameters by 
files:
/proc/.../qpolicies/simple/
/proc/.../qpolicies/prio/
/proc/.../qpolicies/prio/priority: <empty>
/proc/.../qpolicies/prio/timeout: <empty>
Which layout do you find better?
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| > It was for this part that I looked at netlink. This goes into the
| > direction of a new API or at least API extensions.
| > 
| We basically need a callback from code that can access struct sock...
| 
| > (...)
| > For per-socket statistics there is indeed a need for a notification
| > mechanism. If a synchronous mechanism is sufficient, then something like
| > the current CCID-3 getsockopt(DCCP_SOCKOPT_CCID_{RX,TX}_INFO) can be used.
| >
| Synchronous mechanism is acceptable but callback (at least as an option) would 
| be way nicer.
| 
I have been looking around for alternatives - there are some
very good solutions for such aspects in the SCTP subsystem. 

They implement the subscription of event notifications on a socket for
all sorts of events.

A socket option performs this subscription, notifications are then passed
along with data (I think also without, have not dug deep enough into the
sources), via recvmsg(). This is the inverse path to qpolicies: the
ancillary data is passed via cmsg(3) wrappers to the user.

To distinguish events from normal (ancillary) data, SCTP sets the
flag fields to MSG_NOTIFICATION.

There are two good papers on this (the second one is a bit older):
http://www.bsdcan.org/2008/schedule/events/91.en.html
http://lwn.net/2001/features/OLS/pdf/pdf/sctp.pdf

The sources are in net/sctp, the lksctp project is hosted at
http://sourceforge.net/projects/lksctp

I think that this approach is elegant and has something to offer for
DCCP as well. What do you think?

| Ok, but if we are at hackish ideas what about this one: use dccp_ioctl to 
| wait on a mutex. If an event occurs we release mutex thus allowing dccp_ioctl 
| to finish execution and consequently informing user that something 
| interesting has just happened - what it exactly is would have to be 
| determined by other means.
| 
I am trying to think in terms of how much documentation this would need
in order to explain to someone how to use it. It seems feasible, but to
me a bit complicated.


| > The best that I can think of is to map a segment of userspace memory
| > into the kernel and use this memory area as a (ready-only) statistics
| > struct. That would save the system call overhead of using getsockopt().
| >
| I don't think the syscall overhead is big enough to care. After all you don't 
| need statistics that often. Shared memory creates potential problems with 
| synchronization (ok, it is read-only but you need to provide consistent 
| data). Plus you must update them whether needed or not because you never know 
| when the user will want to read them (it may be a problem in some scenarios 
| and may not be a problem in others). IMO more problems that it's worth.
Yes that was why I had reservations against using the ringbuffer API by Lai/Kohler
(implemented for TCP in	http://heim.ifi.uio.no/paalh/publications/files/ism07.pdf ).

We could consider this for later, but it does not seem easy to do this
both in a safe and in a non-complicated way.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

| > It was for this part that I looked at netlink. This goes into the
| > direction of a new API or at least API extensions.
| > 
| We basically need a callback from code that can access struct sock...
| 
| > (...)
| > For per-socket statistics there is indeed a need for a notification
| > mechanism. If a synchronous mechanism is sufficient, then something like
| > the current CCID-3 getsockopt(DCCP_SOCKOPT_CCID_{RX,TX}_INFO) can be used.
| >
| Synchronous mechanism is acceptable but callback (at least as an option) would 
| be way nicer.
| 
I have been looking around for alternatives - there are some
very good solutions for such aspects in the SCTP subsystem. 

They implement the subscription of event notifications on a socket for
all sorts of events.

A socket option performs this subscription, notifications are then passed
along with data (I think also without, have not dug deep enough into the
sources), via recvmsg(). This is the inverse path to qpolicies: the
ancillary data is passed via cmsg(3) wrappers to the user.

To distinguish events from normal (ancillary) data, SCTP sets the
flag fields to MSG_NOTIFICATION.

There are two good papers on this (the second one is a bit older):
http://www.bsdcan.org/2008/schedule/events/91.en.html
http://lwn.net/2001/features/OLS/pdf/pdf/sctp.pdf

The sources are in net/sctp, the lksctp project is hosted at
http://sourceforge.net/projects/lksctp

I think that this approach is elegant and has something to offer for
DCCP as well. What do you think?

| Ok, but if we are at hackish ideas what about this one: use dccp_ioctl to 
| wait on a mutex. If an event occurs we release mutex thus allowing dccp_ioctl 
| to finish execution and consequently informing user that something 
| interesting has just happened - what it exactly is would have to be 
| determined by other means.
| 
I am trying to think in terms of how much documentation this would need
in order to explain to someone how to use it. It seems feasible, but to
me a bit complicated.


| > The best that I can think of is to map a segment of userspace memory
| > into the kernel and use this memory area as a (ready-only) statistics
| > struct. That would save the system call overhead of using getsockopt().
| >
| I don't think the syscall overhead is big enough to care. After all you don't 
| need statistics that often. Shared memory creates potential problems with 
| synchronization (ok, it is read-only but you need to provide consistent 
| data). Plus you must update them whether needed or not because you never know 
| when the user will want to read them (it may be a problem in some scenarios 
| and may not be a problem in others). IMO more problems that it's worth.
Yes that was why I had reservations against using the ringbuffer API by Lai/Kohler
(implemented for TCP in	http://heim.ifi.uio.no/paalh/publications/files/ism07.pdf ).

We could consider this for later, but it does not seem easy to do this
both in a safe and in a non-complicated way.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Monday 02 of June 2008, Gerrit Renker napisa³:
> | > It was for this part that I looked at netlink. This goes into the
> | > direction of a new API or at least API extensions.
> |
> | We basically need a callback from code that can access struct sock...
> |
> | > (...)
> | > For per-socket statistics there is indeed a need for a notification
> | > mechanism. If a synchronous mechanism is sufficient, then something
> | > like the current CCID-3 getsockopt(DCCP_SOCKOPT_CCID_{RX,TX}_INFO) can
> | > be used.
> |
> | Synchronous mechanism is acceptable but callback (at least as an option)
> | would be way nicer.
>
> I have been looking around for alternatives - there are some
> very good solutions for such aspects in the SCTP subsystem.
>
> They implement the subscription of event notifications on a socket for
> all sorts of events.
>
> A socket option performs this subscription, notifications are then passed
> along with data (I think also without, have not dug deep enough into the
> sources), via recvmsg(). This is the inverse path to qpolicies: the
> ancillary data is passed via cmsg(3) wrappers to the user.
>
> To distinguish events from normal (ancillary) data, SCTP sets the
> flag fields to MSG_NOTIFICATION.
>
> There are two good papers on this (the second one is a bit older):
> http://www.bsdcan.org/2008/schedule/events/91.en.html
> http://lwn.net/2001/features/OLS/pdf/pdf/sctp.pdf
>
> The sources are in net/sctp, the lksctp project is hosted at
> http://sourceforge.net/projects/lksctp
>
> I think that this approach is elegant and has something to offer for
> DCCP as well. What do you think?
>
I also thought about such a solution but I didn't state it because I thought 
it is even more hackish than the one below. Mostly because it 
interleaves "real data" with events (and there is no logical connection 
between the two as opposed to sending scenario). But if it is used in SCTP 
then maybe the whole idea is not that bad...
Anyway, I'll have a look at the documents and at the SCTP implementation.

> | Ok, but if we are at hackish ideas what about this one: use dccp_ioctl to
> | wait on a mutex. If an event occurs we release mutex thus allowing
> | dccp_ioctl to finish execution and consequently informing user that
> | something interesting has just happened - what it exactly is would have
> | to be determined by other means.
>
> I am trying to think in terms of how much documentation this would need
> in order to explain to someone how to use it. It seems feasible, but to
> me a bit complicated.
>
The basic idea is the same as above. The difference is that it would overload 
ioctl, not recv. But maybe we should use recv. Not because it is in any way 
better but just because it is already used that way in SCTP and has a few 
documents describing the approach.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Monday 02 of June 2008, Gerrit Renker napisał:
> | > It was for this part that I looked at netlink. This goes into the
> | > direction of a new API or at least API extensions.
> |
> | We basically need a callback from code that can access struct sock...
> |
> | > (...)
> | > For per-socket statistics there is indeed a need for a notification
> | > mechanism. If a synchronous mechanism is sufficient, then something
> | > like the current CCID-3 getsockopt(DCCP_SOCKOPT_CCID_{RX,TX}_INFO) can
> | > be used.
> |
> | Synchronous mechanism is acceptable but callback (at least as an option)
> | would be way nicer.
>
> I have been looking around for alternatives - there are some
> very good solutions for such aspects in the SCTP subsystem.
>
> They implement the subscription of event notifications on a socket for
> all sorts of events.
>
> A socket option performs this subscription, notifications are then passed
> along with data (I think also without, have not dug deep enough into the
> sources), via recvmsg(). This is the inverse path to qpolicies: the
> ancillary data is passed via cmsg(3) wrappers to the user.
>
> To distinguish events from normal (ancillary) data, SCTP sets the
> flag fields to MSG_NOTIFICATION.
>
> There are two good papers on this (the second one is a bit older):
> http://www.bsdcan.org/2008/schedule/events/91.en.html
> http://lwn.net/2001/features/OLS/pdf/pdf/sctp.pdf
>
> The sources are in net/sctp, the lksctp project is hosted at
> http://sourceforge.net/projects/lksctp
>
> I think that this approach is elegant and has something to offer for
> DCCP as well. What do you think?
>
I also thought about such a solution but I didn't state it because I thought 
it is even more hackish than the one below. Mostly because it 
interleaves "real data" with events (and there is no logical connection 
between the two as opposed to sending scenario). But if it is used in SCTP 
then maybe the whole idea is not that bad...
Anyway, I'll have a look at the documents and at the SCTP implementation.

> | Ok, but if we are at hackish ideas what about this one: use dccp_ioctl to
> | wait on a mutex. If an event occurs we release mutex thus allowing
> | dccp_ioctl to finish execution and consequently informing user that
> | something interesting has just happened - what it exactly is would have
> | to be determined by other means.
>
> I am trying to think in terms of how much documentation this would need
> in order to explain to someone how to use it. It seems feasible, but to
> me a bit complicated.
>
The basic idea is the same as above. The difference is that it would overload 
ioctl, not recv. But maybe we should use recv. Not because it is in any way 
better but just because it is already used that way in SCTP and has a few 
documents describing the approach.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| Now that I had a closer look at implementing this functionality I have a few 
| questions:
| 1. Where should information about available qpolicies and their parametrs be 
| exported? Would /proc/net/dccp/qpolicies/ be a good choice?
For a sketch or a first implementation, procfs sounds like a good starting point.

But since it is about dynamic runtime configuration, how about using sysfs or configfs
instead? This is a brainstorming question, I think that sysfs is generally preferred.
I don't know how well configfs has taken off, it is similar, but needs to be
added in the configuration (under Pseudeo Filesystems, CONFIG_CONFIGFS_FS=y|m)
http://lwn.net/Articles/148973/
and Documentation/filesystems/configs. But this could be done later as well.


| 2. I guess we should have at least one file per qpolicy with parameters listed 
| inside. Like that:
| /proc/.../qpolicies/simple: <empty>
| /proc/.../qpolicies/prio: 1 (DCCP_SCM_PRIORITY) 2 (DCCP_SCM_TIMEOUT)
Hm this is a "policy" question -- isn't the `timeout' policy a
standalone variant?

| But we could also have qpolicy represented by directory and parameters by files:
| /proc/.../qpolicies/simple/
| /proc/.../qpolicies/prio/
| /proc/.../qpolicies/prio/priority: <empty>
| /proc/.../qpolicies/prio/timeout: <empty>
| Which layout do you find better?
| -- 
I don't like the empty files. In the procfs for thinkpad Acpi
configuration, for example, there is a line that says which commands are
acceptable, similar for /sys/power/state. In that way, the (sysfs|procfs) file
documents itself and tells the user what can be done with it. It would
be great if the qpolicies could do something similar.

I would start with the utterly simplest possible implementation and
leave complex cases for later. For a sophisticated, elegant
implementation, I would seriously consider sysfs or configs.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

| Now that I had a closer look at implementing this functionality I have a few 
| questions:
| 1. Where should information about available qpolicies and their parametrs be 
| exported? Would /proc/net/dccp/qpolicies/ be a good choice?
For a sketch or a first implementation, procfs sounds like a good starting point.

But since it is about dynamic runtime configuration, how about using sysfs or configfs
instead? This is a brainstorming question, I think that sysfs is generally preferred.
I don't know how well configfs has taken off, it is similar, but needs to be
added in the configuration (under Pseudeo Filesystems, CONFIG_CONFIGFS_FS=y|m)
http://lwn.net/Articles/148973/
and Documentation/filesystems/configs. But this could be done later as well.


| 2. I guess we should have at least one file per qpolicy with parameters listed 
| inside. Like that:
| /proc/.../qpolicies/simple: <empty>
| /proc/.../qpolicies/prio: 1 (DCCP_SCM_PRIORITY) 2 (DCCP_SCM_TIMEOUT)
Hm this is a "policy" question -- isn't the `timeout' policy a
standalone variant?

| But we could also have qpolicy represented by directory and parameters by files:
| /proc/.../qpolicies/simple/
| /proc/.../qpolicies/prio/
| /proc/.../qpolicies/prio/priority: <empty>
| /proc/.../qpolicies/prio/timeout: <empty>
| Which layout do you find better?
| -- 
I don't like the empty files. In the procfs for thinkpad Acpi
configuration, for example, there is a line that says which commands are
acceptable, similar for /sys/power/state. In that way, the (sysfs|procfs) file
documents itself and tells the user what can be done with it. It would
be great if the qpolicies could do something similar.

I would start with the utterly simplest possible implementation and
leave complex cases for later. For a sophisticated, elegant
implementation, I would seriously consider sysfs or configs.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Wednesday 04 of June 2008, Gerrit Renker napisa³:
> | Now that I had a closer look at implementing this functionality I have a
> | few questions:
> | 1. Where should information about available qpolicies and their parametrs
> | be exported? Would /proc/net/dccp/qpolicies/ be a good choice?
>
> For a sketch or a first implementation, procfs sounds like a good starting
> point.
>
> But since it is about dynamic runtime configuration, how about using sysfs
> or configfs instead? This is a brainstorming question, I think that sysfs
> is generally preferred. I don't know how well configfs has taken off, it is
> similar, but needs to be added in the configuration (under Pseudeo
> Filesystems, CONFIG_CONFIGFS_FS=y|m) http://lwn.net/Articles/148973/
> and Documentation/filesystems/configs. But this could be done later as
> well.
>
procfs has some fine example of being used for this kind of information, 
namely /proc/cpuinfo and /proc/meminfo
sysfs: from sysfs-rules.txt: "(...) the sysfs interface cannot provide a 
stable interface (...)"
configfs is for configuring kernel from userspace. Which is quite opposite to  
what we want.

> | 2. I guess we should have at least one file per qpolicy with parameters
> | listed inside. Like that:
> | /proc/.../qpolicies/simple: <empty>
> | /proc/.../qpolicies/prio: 1 (DCCP_SCM_PRIORITY) 2 (DCCP_SCM_TIMEOUT)
>
> Hm this is a "policy" question -- isn't the `timeout' policy a
> standalone variant?
>
It seems we have a bit different views on the subject. But that's to be 
decided when somebody comes round to implementing timeout.

> | But we could also have qpolicy represented by directory and parameters by
> | files: /proc/.../qpolicies/simple/
> | /proc/.../qpolicies/prio/
> | /proc/.../qpolicies/prio/priority: <empty>
> | /proc/.../qpolicies/prio/timeout: <empty>
> | Which layout do you find better?
> | --
>
> I don't like the empty files. In the procfs for thinkpad Acpi
> configuration, for example, there is a line that says which commands are
> acceptable, similar for /sys/power/state. In that way, the (sysfs|procfs)
> file documents itself and tells the user what can be done with it. It would
> be great if the qpolicies could do something similar.
>
Ok, I'll try to write a simple patch for that.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Wednesday 04 of June 2008, Gerrit Renker napisał:
> | Now that I had a closer look at implementing this functionality I have a
> | few questions:
> | 1. Where should information about available qpolicies and their parametrs
> | be exported? Would /proc/net/dccp/qpolicies/ be a good choice?
>
> For a sketch or a first implementation, procfs sounds like a good starting
> point.
>
> But since it is about dynamic runtime configuration, how about using sysfs
> or configfs instead? This is a brainstorming question, I think that sysfs
> is generally preferred. I don't know how well configfs has taken off, it is
> similar, but needs to be added in the configuration (under Pseudeo
> Filesystems, CONFIG_CONFIGFS_FS=y|m) http://lwn.net/Articles/148973/
> and Documentation/filesystems/configs. But this could be done later as
> well.
>
procfs has some fine example of being used for this kind of information, 
namely /proc/cpuinfo and /proc/meminfo
sysfs: from sysfs-rules.txt: "(...) the sysfs interface cannot provide a 
stable interface (...)"
configfs is for configuring kernel from userspace. Which is quite opposite to  
what we want.

> | 2. I guess we should have at least one file per qpolicy with parameters
> | listed inside. Like that:
> | /proc/.../qpolicies/simple: <empty>
> | /proc/.../qpolicies/prio: 1 (DCCP_SCM_PRIORITY) 2 (DCCP_SCM_TIMEOUT)
>
> Hm this is a "policy" question -- isn't the `timeout' policy a
> standalone variant?
>
It seems we have a bit different views on the subject. But that's to be 
decided when somebody comes round to implementing timeout.

> | But we could also have qpolicy represented by directory and parameters by
> | files: /proc/.../qpolicies/simple/
> | /proc/.../qpolicies/prio/
> | /proc/.../qpolicies/prio/priority: <empty>
> | /proc/.../qpolicies/prio/timeout: <empty>
> | Which layout do you find better?
> | --
>
> I don't like the empty files. In the procfs for thinkpad Acpi
> configuration, for example, there is a line that says which commands are
> acceptable, similar for /sys/power/state. In that way, the (sysfs|procfs)
> file documents itself and tells the user what can be done with it. It would
> be great if the qpolicies could do something similar.
>
Ok, I'll try to write a simple patch for that.
-- 
Regards,
Tomasz Grobelny

[PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace through procfs

[Tomasz Grobelny]

Since packets with invalid cmsg parameters can be rejected by kernel there
is a need to allow applications to access information on available policies
and their respective cmsg parameters at runtime. This patch simplifies
maintaining compatibility between userspace applications and DCCP code.
Information is available through files in /proc/net/dccp/qpolicies/

Signed-off-by: Tomasz Grobelny <tomasz@grobelny.oswiecenia.net>
---
 net/dccp/dccp.h    |    3 ++
 net/dccp/proto.c   |    6 +++++
 net/dccp/qpolicy.c |   57 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 66 insertions(+), 0 deletions(-)

diff --git a/net/dccp/dccp.h b/net/dccp/dccp.h
index c6e1a9c..49931b6 100644
--- a/net/dccp/dccp.h
+++ b/net/dccp/dccp.h
@@ -224,6 +224,9 @@ extern void		dccp_qpolicy_drop(struct sock *sk, struct sk_buff *skb);
 extern struct sk_buff	*dccp_qpolicy_top(struct sock *sk);
 extern struct sk_buff	*dccp_qpolicy_pop(struct sock *sk);
 
+extern int 		dccp_qpolicy_init(void);
+extern void		dccp_qpolicy_exit(void);
+
 /*
  * TX Packet Output and TX Timers
  */
diff --git a/net/dccp/proto.c b/net/dccp/proto.c
index bdc4126..71cbe56 100644
--- a/net/dccp/proto.c
+++ b/net/dccp/proto.c
@@ -1186,9 +1186,15 @@ static int __init dccp_init(void)
 	if (rc)
 		goto out_ackvec_exit;
 
+	rc = dccp_qpolicy_init();
+	if (rc)
+		goto out_qpolicy_exit;
+
 	dccp_timestamping_init();
 out:
 	return rc;
+out_qpolicy_exit:
+	dccp_qpolicy_exit();
 out_ackvec_exit:
 	dccp_ackvec_exit();
 out_free_dccp_mib:
diff --git a/net/dccp/qpolicy.c b/net/dccp/qpolicy.c
index 4270c7f..3d1a095 100644
--- a/net/dccp/qpolicy.c
+++ b/net/dccp/qpolicy.c
@@ -10,6 +10,7 @@
  *  as published by the Free Software Foundation.
  */
 #include <asm/unaligned.h>
+#include <linux/proc_fs.h>
 #include "dccp.h"
 
 /*
@@ -125,3 +126,59 @@ struct sk_buff *dccp_qpolicy_pop(struct sock *sk)
 		skb_unlink(skb, &sk->sk_write_queue);
 	return skb;
 }
+
+int proc_read_qpolicy_params(char *page, char **start,
+				off_t off, int count,
+				int *eof, void *data)
+{
+	return sprintf(page, "%s\n", (char*)data);
+}
+
+static struct proc_dir_entry *qpolicies_dir;
+static struct proc_dir_entry *qpol_entries[2*DCCPQ_POLICY_MAX];
+static int entry_counter = 0;
+
+void add_qpol_info(int qpol_number, char* symlink, char* content)
+{
+	struct proc_dir_entry *qpol_file, *qpol_symlink;
+	char name[10];
+	sprintf(name, "%d", qpol_number);
+
+	qpol_file = create_proc_read_entry(name, 0444, qpolicies_dir,
+					proc_read_qpolicy_params, content);
+	if(qpol_file = NULL)
+		return;
+	qpol_file->owner = THIS_MODULE;
+	qpol_entries[entry_counter++] = qpol_file;
+
+	qpol_symlink = proc_symlink(symlink, qpolicies_dir, name);
+	if(qpol_symlink = NULL)
+		return;
+	qpol_symlink->owner = THIS_MODULE;
+	qpol_entries[entry_counter++] = qpol_symlink;
+}
+
+int dccp_qpolicy_init()
+{
+	char buffer[2048];
+	proc_mkdir("dccp", init_net.proc_net);
+	qpolicies_dir = proc_mkdir("dccp/qpolicies", init_net.proc_net);
+	if(qpolicies_dir = NULL)
+		return -ENOMEM;
+
+	add_qpol_info(DCCPQ_POLICY_SIMPLE, "simple", "");
+
+	sprintf(buffer, "%d priority\n", DCCP_SCM_PRIORITY);
+	add_qpol_info(DCCPQ_POLICY_PRIO, "prio", buffer);
+
+	return 0;
+}
+
+void dccp_qpolicy_exit()
+{
+	int i = 0;
+	for(i=0;i<entry_counter;i++)
+		remove_proc_entry(qpol_entries[i]->name, qpolicies_dir);
+	remove_proc_entry("dccp/qpolicies", init_net.proc_net);
+	entry_counter = 0;
+}
-- 
1.5.4.5

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| > But since it is about dynamic runtime configuration, how about using sysfs
| > or configfs instead? This is a brainstorming question, I think that sysfs
| > is generally preferred. I don't know how well configfs has taken off, it is
| > similar, but needs to be added in the configuration (under Pseudeo
| > Filesystems, CONFIG_CONFIGFS_FS=y|m) http://lwn.net/Articles/148973/
| > and Documentation/filesystems/configs. But this could be done later as
| > well.
| >
| procfs has some fine example of being used for this kind of information, 
| namely /proc/cpuinfo and /proc/meminfo

| sysfs: from sysfs-rules.txt: "(...) the sysfs interface cannot provide a 
| stable interface (...)"
Yes that is a key point and I think we are talking about the same point here.

I had mentioned sysfs/procfs as alternatives not because they are the best
possible match, but since it shows that similar problems (and likely solutions)
exist also in other areas.

But there are also areas where the rate of change is relatively low or
even absent: Documentation/ABI/README for instance mentions 4 different
levels of stability (stable/testing/obsolete/removed), the most entries
are under `testing'.

| configfs is for configuring kernel from userspace. Which is quite opposite to  
| what we want.
| 
Ok I think I understand now where you are heading - but then we can go a much
simpler route: why not implement a sysctl (which is also mirrored in /proc/sys)
that contains all available/implemented qpolicies as a space-separated
string, such as

	cat /proc/sys/net/ipv4/tcp_available_congestion_control ?

And I think that it is unnecessarily complex to add the available parameters
belonging to each qpolicy as well.

If we agree on using unique strings to identify qpolicies then we can
keep the runtime discovery much simpler. I think a manpage would be more
helpful here, since the runtime discovery of parameters is not
immediately obvious.

- Gerrit

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

| > But since it is about dynamic runtime configuration, how about using sysfs
| > or configfs instead? This is a brainstorming question, I think that sysfs
| > is generally preferred. I don't know how well configfs has taken off, it is
| > similar, but needs to be added in the configuration (under Pseudeo
| > Filesystems, CONFIG_CONFIGFS_FS=y|m) http://lwn.net/Articles/148973/
| > and Documentation/filesystems/configs. But this could be done later as
| > well.
| >
| procfs has some fine example of being used for this kind of information, 
| namely /proc/cpuinfo and /proc/meminfo

| sysfs: from sysfs-rules.txt: "(...) the sysfs interface cannot provide a 
| stable interface (...)"
Yes that is a key point and I think we are talking about the same point here.

I had mentioned sysfs/procfs as alternatives not because they are the best
possible match, but since it shows that similar problems (and likely solutions)
exist also in other areas.

But there are also areas where the rate of change is relatively low or
even absent: Documentation/ABI/README for instance mentions 4 different
levels of stability (stable/testing/obsolete/removed), the most entries
are under `testing'.

| configfs is for configuring kernel from userspace. Which is quite opposite to  
| what we want.
| 
Ok I think I understand now where you are heading - but then we can go a much
simpler route: why not implement a sysctl (which is also mirrored in /proc/sys)
that contains all available/implemented qpolicies as a space-separated
string, such as

	cat /proc/sys/net/ipv4/tcp_available_congestion_control ?

And I think that it is unnecessarily complex to add the available parameters
belonging to each qpolicy as well.

If we agree on using unique strings to identify qpolicies then we can
keep the runtime discovery much simpler. I think a manpage would be more
helpful here, since the runtime discovery of parameters is not
immediately obvious.

- Gerrit

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Tuesday 10 of June 2008, Gerrit Renker napisa³:
> | > But since it is about dynamic runtime configuration, how about using
> | > sysfs or configfs instead? This is a brainstorming question, I think
> | > that sysfs is generally preferred. I don't know how well configfs has
> | > taken off, it is similar, but needs to be added in the configuration
> | > (under Pseudeo Filesystems, CONFIG_CONFIGFS_FS=y|m)
> | > http://lwn.net/Articles/148973/ and Documentation/filesystems/configs.
> | > But this could be done later as well.
> |
> | procfs has some fine example of being used for this kind of information,
> | namely /proc/cpuinfo and /proc/meminfo
> |
> | sysfs: from sysfs-rules.txt: "(...) the sysfs interface cannot provide a
> | stable interface (...)"
>
> Yes that is a key point and I think we are talking about the same point
> here.
>
> I had mentioned sysfs/procfs as alternatives not because they are the best
> possible match, but since it shows that similar problems (and likely
> solutions) exist also in other areas.
>
That's ok, I just mention what I know about them so that we can have complete 
argumentation for/against given solution.

> But there are also areas where the rate of change is relatively low or
> even absent: Documentation/ABI/README for instance mentions 4 different
> levels of stability (stable/testing/obsolete/removed), the most entries
> are under `testing'.
>
This one should probably be marked as testing too. And probably be moved to 
stable with time (when it proves useful for applications).

> | configfs is for configuring kernel from userspace. Which is quite
> | opposite to what we want.
>
> Ok I think I understand now where you are heading - but then we can go a
> much simpler route: why not implement a sysctl (which is also mirrored in
> /proc/sys) that contains all available/implemented qpolicies as a
> space-separated string, such as
>
> 	cat /proc/sys/net/ipv4/tcp_available_congestion_control ?
>
Could be /proc/sys. I just had an impression that sysctls are for setting 
certain variables used in kernel. But as far as I understand it the 
difference is highly subjective and I'm ok with both /proc and /proc/sys. 
Would be nice to have more opinions (Arnaldo? others?) whether we should 
favour one over other.

> And I think that it is unnecessarily complex to add the available
> parameters belonging to each qpolicy as well.
>
I think it is critical. If the application just wants to know which qpolicies 
are available it can try to set it with setsockopt(). If it gets an error 
given qpolicy is unavailable. As simple as that. No need for additional 
interface.
But if the application wants information about implemented parameters there is 
currently no way to get it. It can try to send() packet and check return 
value (which is quite a hack to be honest). It will work if the parameter is 
not implemented at all. But what happens when you try to set priority for a 
packet and use "simple" qpolicy? AFAIR nothing - you get no information 
whatsoever that this parameter will not be used inside qpolicy.

And that's why we need information about parameters in /proc or /proc/sys.

> If we agree on using unique strings to identify qpolicies then we can
> keep the runtime discovery much simpler. I think a manpage would be more
> helpful here, since the runtime discovery of parameters is not
> immediately obvious.
>
Manpage of what? Documentation is certainly needed but before writing one we 
need to have a basic implementation we agree upon.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Tuesday 10 of June 2008, Gerrit Renker napisał:
> | > But since it is about dynamic runtime configuration, how about using
> | > sysfs or configfs instead? This is a brainstorming question, I think
> | > that sysfs is generally preferred. I don't know how well configfs has
> | > taken off, it is similar, but needs to be added in the configuration
> | > (under Pseudeo Filesystems, CONFIG_CONFIGFS_FS=y|m)
> | > http://lwn.net/Articles/148973/ and Documentation/filesystems/configs.
> | > But this could be done later as well.
> |
> | procfs has some fine example of being used for this kind of information,
> | namely /proc/cpuinfo and /proc/meminfo
> |
> | sysfs: from sysfs-rules.txt: "(...) the sysfs interface cannot provide a
> | stable interface (...)"
>
> Yes that is a key point and I think we are talking about the same point
> here.
>
> I had mentioned sysfs/procfs as alternatives not because they are the best
> possible match, but since it shows that similar problems (and likely
> solutions) exist also in other areas.
>
That's ok, I just mention what I know about them so that we can have complete 
argumentation for/against given solution.

> But there are also areas where the rate of change is relatively low or
> even absent: Documentation/ABI/README for instance mentions 4 different
> levels of stability (stable/testing/obsolete/removed), the most entries
> are under `testing'.
>
This one should probably be marked as testing too. And probably be moved to 
stable with time (when it proves useful for applications).

> | configfs is for configuring kernel from userspace. Which is quite
> | opposite to what we want.
>
> Ok I think I understand now where you are heading - but then we can go a
> much simpler route: why not implement a sysctl (which is also mirrored in
> /proc/sys) that contains all available/implemented qpolicies as a
> space-separated string, such as
>
> 	cat /proc/sys/net/ipv4/tcp_available_congestion_control ?
>
Could be /proc/sys. I just had an impression that sysctls are for setting 
certain variables used in kernel. But as far as I understand it the 
difference is highly subjective and I'm ok with both /proc and /proc/sys. 
Would be nice to have more opinions (Arnaldo? others?) whether we should 
favour one over other.

> And I think that it is unnecessarily complex to add the available
> parameters belonging to each qpolicy as well.
>
I think it is critical. If the application just wants to know which qpolicies 
are available it can try to set it with setsockopt(). If it gets an error 
given qpolicy is unavailable. As simple as that. No need for additional 
interface.
But if the application wants information about implemented parameters there is 
currently no way to get it. It can try to send() packet and check return 
value (which is quite a hack to be honest). It will work if the parameter is 
not implemented at all. But what happens when you try to set priority for a 
packet and use "simple" qpolicy? AFAIR nothing - you get no information 
whatsoever that this parameter will not be used inside qpolicy.

And that's why we need information about parameters in /proc or /proc/sys.

> If we agree on using unique strings to identify qpolicies then we can
> keep the runtime discovery much simpler. I think a manpage would be more
> helpful here, since the runtime discovery of parameters is not
> immediately obvious.
>
Manpage of what? Documentation is certainly needed but before writing one we 
need to have a basic implementation we agree upon.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| > But there are also areas where the rate of change is relatively low or
| > even absent: Documentation/ABI/README for instance mentions 4 different
| > levels of stability (stable/testing/obsolete/removed), the most entries
| > are under `testing'.
| >
| This one should probably be marked as testing too. And probably be moved to 
| stable with time (when it proves useful for applications).
| 
In the test tree there are two levels of testing:

 * any subtrees tree are open for writing experimental patches,
   for refinement, and for patches that may be rewritten later;

 * the test tree itself is for later consideration in mainline and therefore
   is more conservative. The main reason for keeping the patches in that tree
   is to extend the phase of patch review, to filter out bugs that may still
   lurk somewhere, so that regressions are minimised when submitting.


| > why not implement a sysctl (which is also mirrored in
| > /proc/sys) that contains all available/implemented qpolicies as a
| > space-separated string, such as
| >
| > 	cat /proc/sys/net/ipv4/tcp_available_congestion_control ?
| >
| Could be /proc/sys. I just had an impression that sysctls are for setting 
| certain variables used in kernel. But as far as I understand it the 
| difference is highly subjective and I'm ok with both /proc and /proc/sys. 
Yes that is not immediately obvious, there are far more sysctls with write
permissions than informative/read-only sysctls:
 * read-only:   7 entries with  `find /proc/sys/net/ -perm  444` 
 * write:     486 entries with  `find /proc/sys/net/ -perm /222`


| Would be nice to have more opinions (Arnaldo? others?) whether we should 
| favour one over other.
Agree with this call. 


| But if the application wants information about implemented parameters there is 
| currently no way to get it. It can try to send() packet and check return 
| value (which is quite a hack to be honest). It will work if the parameter is 
| not implemented at all. But what happens when you try to set priority for a 
| packet and use "simple" qpolicy? AFAIR nothing - you get no information 
| whatsoever that this parameter will not be used inside qpolicy.
| 
| And that's why we need information about parameters in /proc or /proc/sys.
| 
Sorry I can't see here why we need information about parameters. When
introducing a new socket option there is a convention of how to use it.

For sockopts, the type of the argument is listed for each option type.

With qpolicies, there is one more indirection, since there is no
immediate return value. But even for this kind of socket option there
exist similar cases, for instance in the manpage of ipv6(7)
 * IPV6_RECVERR (boolean) sets delivery of error messages which return a "struct
   sock_extended_err" via cmsg(3) when MSG_ERRQUEUE is set in recvmsg(2)
 * IPV6_PKTINFO (boolean) sets the delivery of IPV6_PKTINFO control messages,
   and this one has an associated constraint - works only on SOCK_DGRAM/SOCK_RAW


| > If we agree on using unique strings to identify qpolicies then we can
| > keep the runtime discovery much simpler. I think a manpage would be more
| > helpful here, since the runtime discovery of parameters is not
| > immediately obvious.
| >
| Manpage of what? Documentation is certainly needed but before writing one we 
| need to have a basic implementation we agree upon.
| -- 
There is indeed a misunderstanding.

We have already an implementation we agreed upon:
http://eden-feed.erg.abdn.ac.uk/cgi-bin/gitweb.cgi?p‹cp_exp.git;a=commitdiff;hácf8b3ce96397f934775617ba24eb1ff404747a

With a manpage I mean to document 
 * how the two currently available qpolicies ("simple" and "prio") are enabled;
 * which additional constraints they have (e.g. how they interpret tx_qlen);
 * information specific to a policy (e.g. that higher priority values in the
   "prio" policy mean a higher priority, comparable to SO_PRIORITY in socket(7));
 * which ancillary data the policies require (the procfs parameters)
   - simple: no ancillary parameters
   - prio:   u32 priority value, passed as DCCP_SCM_PRIORITY via cmsg(3),
             using a level of SOL_DCCP and a length of CMSG_LEN(sizeof(uint32_t));
 * ... probably I have missed something here

With that kind of documentation, I think, we would not need runtime discovery
of parameters.
--
To unsubscribe from this list: send the line "unsubscribe dccp" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

| > But there are also areas where the rate of change is relatively low or
| > even absent: Documentation/ABI/README for instance mentions 4 different
| > levels of stability (stable/testing/obsolete/removed), the most entries
| > are under `testing'.
| >
| This one should probably be marked as testing too. And probably be moved to 
| stable with time (when it proves useful for applications).
| 
In the test tree there are two levels of testing:

 * any subtrees tree are open for writing experimental patches,
   for refinement, and for patches that may be rewritten later;

 * the test tree itself is for later consideration in mainline and therefore
   is more conservative. The main reason for keeping the patches in that tree
   is to extend the phase of patch review, to filter out bugs that may still
   lurk somewhere, so that regressions are minimised when submitting.


| > why not implement a sysctl (which is also mirrored in
| > /proc/sys) that contains all available/implemented qpolicies as a
| > space-separated string, such as
| >
| > 	cat /proc/sys/net/ipv4/tcp_available_congestion_control ?
| >
| Could be /proc/sys. I just had an impression that sysctls are for setting 
| certain variables used in kernel. But as far as I understand it the 
| difference is highly subjective and I'm ok with both /proc and /proc/sys. 
Yes that is not immediately obvious, there are far more sysctls with write
permissions than informative/read-only sysctls:
 * read-only:   7 entries with  `find /proc/sys/net/ -perm  444` 
 * write:     486 entries with  `find /proc/sys/net/ -perm /222`


| Would be nice to have more opinions (Arnaldo? others?) whether we should 
| favour one over other.
Agree with this call. 


| But if the application wants information about implemented parameters there is 
| currently no way to get it. It can try to send() packet and check return 
| value (which is quite a hack to be honest). It will work if the parameter is 
| not implemented at all. But what happens when you try to set priority for a 
| packet and use "simple" qpolicy? AFAIR nothing - you get no information 
| whatsoever that this parameter will not be used inside qpolicy.
| 
| And that's why we need information about parameters in /proc or /proc/sys.
| 
Sorry I can't see here why we need information about parameters. When
introducing a new socket option there is a convention of how to use it.

For sockopts, the type of the argument is listed for each option type.

With qpolicies, there is one more indirection, since there is no
immediate return value. But even for this kind of socket option there
exist similar cases, for instance in the manpage of ipv6(7)
 * IPV6_RECVERR (boolean) sets delivery of error messages which return a "struct
   sock_extended_err" via cmsg(3) when MSG_ERRQUEUE is set in recvmsg(2)
 * IPV6_PKTINFO (boolean) sets the delivery of IPV6_PKTINFO control messages,
   and this one has an associated constraint - works only on SOCK_DGRAM/SOCK_RAW


| > If we agree on using unique strings to identify qpolicies then we can
| > keep the runtime discovery much simpler. I think a manpage would be more
| > helpful here, since the runtime discovery of parameters is not
| > immediately obvious.
| >
| Manpage of what? Documentation is certainly needed but before writing one we 
| need to have a basic implementation we agree upon.
| -- 
There is indeed a misunderstanding.

We have already an implementation we agreed upon:
http://eden-feed.erg.abdn.ac.uk/cgi-bin/gitweb.cgi?p=dccp_exp.git;a=commitdiff;h=87cf8b3ce96397f934775617ba24eb1ff404747a

With a manpage I mean to document 
 * how the two currently available qpolicies ("simple" and "prio") are enabled;
 * which additional constraints they have (e.g. how they interpret tx_qlen);
 * information specific to a policy (e.g. that higher priority values in the
   "prio" policy mean a higher priority, comparable to SO_PRIORITY in socket(7));
 * which ancillary data the policies require (the procfs parameters)
   - simple: no ancillary parameters
   - prio:   u32 priority value, passed as DCCP_SCM_PRIORITY via cmsg(3),
             using a level of SOL_DCCP and a length of CMSG_LEN(sizeof(uint32_t));
 * ... probably I have missed something here

With that kind of documentation, I think, we would not need runtime discovery
of parameters.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Thursday 12 of June 2008, Gerrit Renker napisa³:
> | But if the application wants information about implemented parameters
> | there is currently no way to get it. It can try to send() packet and
> | check return value (which is quite a hack to be honest). It will work if
> | the parameter is not implemented at all. But what happens when you try to
> | set priority for a packet and use "simple" qpolicy? AFAIR nothing - you
> | get no information whatsoever that this parameter will not be used inside
> | qpolicy.
> |
> | And that's why we need information about parameters in /proc or
> | /proc/sys.
>
> Sorry I can't see here why we need information about parameters. When
> introducing a new socket option there is a convention of how to use it.
>
> For sockopts, the type of the argument is listed for each option type.
>
You seem to assume that a given qpolicy is a fixed set of functionality at the 
time of submission to the mainline kernel. In that case you are right, the 
application developer knows which parameters he can attach to a packet to be 
sent (and (s)he knows it at the time of development), so no parameter 
detection is necessary.

But I view it a bit differently. I think we have to go back to the discussion 
about how to add the "timeout" parameter (or any other). Basically there are 
two ways:
 1. add a new "timeout" qpolicy (as you proposed),
 2. extend an existing "prio" qpolicy adding DCCP_SCM_TIMEOUT parameter (as I 
propose). BTW, the "prio" name is a bit misleading, the qpolicy should 
probably be named "advanced" or something like that.

In other words the basic question is: do we want to add new parameters to 
existing qpolicies (then we need parameter discovery) or we don't want new 
parameters (then we don't need information about parameters available at 
runtime).

Having defined the alternatives it's time to decide which is better. I, of 
course, claim that mine (which is adding new parameters to existing 
qpolicies). That's simply because I think that providing both 
DCCP_SCM_TIMEOUT and DCCP_SCM_PRIORITY parameters may be useful. And I don't 
see an obvoius way of achieving that goal with "new policy for new parameter" 
approach.

I hope this lengthy text is understandable. Either way, the question is 
simple: what is your concept of adding DCCP_SCM_TIMEOUT parameter?

> | > If we agree on using unique strings to identify qpolicies then we can
> | > keep the runtime discovery much simpler. I think a manpage would be
> | > more helpful here, since the runtime discovery of parameters is not
> | > immediately obvious.
> |
> | Manpage of what? Documentation is certainly needed but before writing one
> | we need to have a basic implementation we agree upon.
> | --
>
> There is indeed a misunderstanding.
>
> We have already an implementation we agreed upon:
> http://eden-feed.erg.abdn.ac.uk/cgi-bin/gitweb.cgi?pÜcp_exp.git;a=commitd
>iff;h‡cf8b3ce96397f934775617ba24eb1ff404747a
>
Yes, but I would consider it not yet ready for application development. Why? 
See subject of this mail and previous paragraphs.

> With a manpage I mean to document
Is there any "man dccp"?

>  * how the two currently available qpolicies ("simple" and "prio") are
> enabled; * which additional constraints they have (e.g. how they interpret
> tx_qlen); * information specific to a policy (e.g. that higher priority
> values in the "prio" policy mean a higher priority, comparable to
> SO_PRIORITY in socket(7)); * which ancillary data the policies require (the
> procfs parameters) - simple: no ancillary parameters
>    - prio:   u32 priority value, passed as DCCP_SCM_PRIORITY via cmsg(3),
>              using a level of SOL_DCCP and a length of
> CMSG_LEN(sizeof(uint32_t)); * ... probably I have missed something here
>
Fine. But where exactly should it be described? Which file? I downloaded 
latest man pages from [1] but dccp is not even mentioned there. Or should a 
new man page be created (which would involve explaining what is dccp in the 
first place)?

[1] http://www.kernel.org/pub/linux/docs/manpages/man-pages-2.80.tar.bz2

> With that kind of documentation, I think, we would not need runtime
> discovery of parameters.
I still don't agree, see previous paragraphs.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Thursday 12 of June 2008, Gerrit Renker napisał:
> | But if the application wants information about implemented parameters
> | there is currently no way to get it. It can try to send() packet and
> | check return value (which is quite a hack to be honest). It will work if
> | the parameter is not implemented at all. But what happens when you try to
> | set priority for a packet and use "simple" qpolicy? AFAIR nothing - you
> | get no information whatsoever that this parameter will not be used inside
> | qpolicy.
> |
> | And that's why we need information about parameters in /proc or
> | /proc/sys.
>
> Sorry I can't see here why we need information about parameters. When
> introducing a new socket option there is a convention of how to use it.
>
> For sockopts, the type of the argument is listed for each option type.
>
You seem to assume that a given qpolicy is a fixed set of functionality at the 
time of submission to the mainline kernel. In that case you are right, the 
application developer knows which parameters he can attach to a packet to be 
sent (and (s)he knows it at the time of development), so no parameter 
detection is necessary.

But I view it a bit differently. I think we have to go back to the discussion 
about how to add the "timeout" parameter (or any other). Basically there are 
two ways:
 1. add a new "timeout" qpolicy (as you proposed),
 2. extend an existing "prio" qpolicy adding DCCP_SCM_TIMEOUT parameter (as I 
propose). BTW, the "prio" name is a bit misleading, the qpolicy should 
probably be named "advanced" or something like that.

In other words the basic question is: do we want to add new parameters to 
existing qpolicies (then we need parameter discovery) or we don't want new 
parameters (then we don't need information about parameters available at 
runtime).

Having defined the alternatives it's time to decide which is better. I, of 
course, claim that mine (which is adding new parameters to existing 
qpolicies). That's simply because I think that providing both 
DCCP_SCM_TIMEOUT and DCCP_SCM_PRIORITY parameters may be useful. And I don't 
see an obvoius way of achieving that goal with "new policy for new parameter" 
approach.

I hope this lengthy text is understandable. Either way, the question is 
simple: what is your concept of adding DCCP_SCM_TIMEOUT parameter?

> | > If we agree on using unique strings to identify qpolicies then we can
> | > keep the runtime discovery much simpler. I think a manpage would be
> | > more helpful here, since the runtime discovery of parameters is not
> | > immediately obvious.
> |
> | Manpage of what? Documentation is certainly needed but before writing one
> | we need to have a basic implementation we agree upon.
> | --
>
> There is indeed a misunderstanding.
>
> We have already an implementation we agreed upon:
> http://eden-feed.erg.abdn.ac.uk/cgi-bin/gitweb.cgi?p=dccp_exp.git;a=commitd
>iff;h=87cf8b3ce96397f934775617ba24eb1ff404747a
>
Yes, but I would consider it not yet ready for application development. Why? 
See subject of this mail and previous paragraphs.

> With a manpage I mean to document
Is there any "man dccp"?

>  * how the two currently available qpolicies ("simple" and "prio") are
> enabled; * which additional constraints they have (e.g. how they interpret
> tx_qlen); * information specific to a policy (e.g. that higher priority
> values in the "prio" policy mean a higher priority, comparable to
> SO_PRIORITY in socket(7)); * which ancillary data the policies require (the
> procfs parameters) - simple: no ancillary parameters
>    - prio:   u32 priority value, passed as DCCP_SCM_PRIORITY via cmsg(3),
>              using a level of SOL_DCCP and a length of
> CMSG_LEN(sizeof(uint32_t)); * ... probably I have missed something here
>
Fine. But where exactly should it be described? Which file? I downloaded 
latest man pages from [1] but dccp is not even mentioned there. Or should a 
new man page be created (which would involve explaining what is dccp in the 
first place)?

[1] http://www.kernel.org/pub/linux/docs/manpages/man-pages-2.80.tar.bz2

> With that kind of documentation, I think, we would not need runtime
> discovery of parameters.
I still don't agree, see previous paragraphs.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| In other words the basic question is: do we want to add new parameters to
| existing qpolicies (then we need parameter discovery) or we don't want new
| parameters (then we don't need information about parameters available at
| runtime).
|
| Having defined the alternatives it's time to decide which is better. I, of
| course, claim that mine (which is adding new parameters to existing
| qpolicies). That's simply because I think that providing both
| DCCP_SCM_TIMEOUT and DCCP_SCM_PRIORITY parameters may be useful. And I don't
| see an obvoius way of achieving that goal with "new policy for new parameter"
| approach.
I agree that providing both parameters may be useful, but don't see this
as a place of contradiction.

In the kernel I think it is best to make it type-safe, i.e. no new parameters
to already-defined policies. But I can't see how this would restrict the use.

In particular, the following is possible:

 (a) defer the dynamic runtime discovery to an application-library (wrappers
     around system calls which, according to the presented information,
     select an appropriate qpolicy and fill in its parameters);
 (b) add rules to allow runtime-switching of policies: for example,a user first
     selects "prio", but then provides a timeout parameter. Instead of returning
     "parameter not understood", the interface could simply `upgrade' the current
     policy from "prio" to "timed-prio". A matrix is below.

| I hope this lengthy text is understandable. Either way, the question is
| simple: what is your concept of adding DCCP_SCM_TIMEOUT parameter?
We find both 'atomic' and 'aggregate' (combined) policies:
 1) "prio"    standalone,
 2) "timeout" standalone,
 3) "prio"    combined with "timeout" (called something like "timed-prio").

With regard to parameters, this leads to the following matrix:

    +-------------+--------+-------------------+------------------+
    | Policy Name | Policy |         Presence of Parameters       |
    |             | ID#    | DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT |
    +-------------+--------+-------------------+------------------+
    | "simple     |   0    |        no         |       no         |
    | "prio"      |   1    |        YES        |       no         |
    | "timed-prio"|   2?   |        YES        |       YES        |
    +-------------+--------+-------------------+------------------+


| > With a manpage I mean to document
| Is there any "man dccp"?
|
Not yet. If you or someone else can find time to contribute towards a DCCP manpage,
that would be just great. The best available information so far is on the OSDL pages
for DCCP and Documentation/networking/dccp.txt.

I think there is a special maintainer for the kernel manpages, who could
be emailed with a basic manpage. But ther ere is a similar problem - if the
API changes frequently, then this requires to update the manpage accordingly.

As alternatives to documentation, there are for example providing
 *running source code,
 * web pages or
 * use cases posted to this list
 * ...

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

| In other words the basic question is: do we want to add new parameters to
| existing qpolicies (then we need parameter discovery) or we don't want new
| parameters (then we don't need information about parameters available at
| runtime).
|
| Having defined the alternatives it's time to decide which is better. I, of
| course, claim that mine (which is adding new parameters to existing
| qpolicies). That's simply because I think that providing both
| DCCP_SCM_TIMEOUT and DCCP_SCM_PRIORITY parameters may be useful. And I don't
| see an obvoius way of achieving that goal with "new policy for new parameter"
| approach.
I agree that providing both parameters may be useful, but don't see this
as a place of contradiction.

In the kernel I think it is best to make it type-safe, i.e. no new parameters
to already-defined policies. But I can't see how this would restrict the use.

In particular, the following is possible:

 (a) defer the dynamic runtime discovery to an application-library (wrappers
     around system calls which, according to the presented information,
     select an appropriate qpolicy and fill in its parameters);
 (b) add rules to allow runtime-switching of policies: for example,a user first
     selects "prio", but then provides a timeout parameter. Instead of returning
     "parameter not understood", the interface could simply `upgrade' the current
     policy from "prio" to "timed-prio". A matrix is below.

| I hope this lengthy text is understandable. Either way, the question is
| simple: what is your concept of adding DCCP_SCM_TIMEOUT parameter?
We find both 'atomic' and 'aggregate' (combined) policies:
 1) "prio"    standalone,
 2) "timeout" standalone,
 3) "prio"    combined with "timeout" (called something like "timed-prio").

With regard to parameters, this leads to the following matrix:

    +-------------+--------+-------------------+------------------+
    | Policy Name | Policy |         Presence of Parameters       |
    |             | ID#    | DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT |
    +-------------+--------+-------------------+------------------+
    | "simple     |   0    |        no         |       no         |
    | "prio"      |   1    |        YES        |       no         |
    | "timed-prio"|   2?   |        YES        |       YES        |
    +-------------+--------+-------------------+------------------+


| > With a manpage I mean to document
| Is there any "man dccp"?
|
Not yet. If you or someone else can find time to contribute towards a DCCP manpage,
that would be just great. The best available information so far is on the OSDL pages
for DCCP and Documentation/networking/dccp.txt.

I think there is a special maintainer for the kernel manpages, who could
be emailed with a basic manpage. But ther ere is a similar problem - if the
API changes frequently, then this requires to update the manpage accordingly.

As alternatives to documentation, there are for example providing
 *running source code,
 * web pages or
 * use cases posted to this list
 * ...

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Tuesday 17 of June 2008, Gerrit Renker napisa³:
> | In other words the basic question is: do we want to add new parameters to
> | existing qpolicies (then we need parameter discovery) or we don't want
> | new parameters (then we don't need information about parameters available
> | at runtime).
> |
> | Having defined the alternatives it's time to decide which is better. I,
> | of course, claim that mine (which is adding new parameters to existing
> | qpolicies). That's simply because I think that providing both
> | DCCP_SCM_TIMEOUT and DCCP_SCM_PRIORITY parameters may be useful. And I
> | don't see an obvoius way of achieving that goal with "new policy for new
> | parameter" approach.
>
> I agree that providing both parameters may be useful, but don't see this
> as a place of contradiction.
>
> In the kernel I think it is best to make it type-safe, i.e. no new
> parameters to already-defined policies. But I can't see how this would
> restrict the use.
> (...)
>
So we would need new policy for each new parameter, right? I somehow don't 
like it but it should work. You are right that this way runtime parameter 
discovery is not necessary. BTW, we will have a bit of a problem with naming 
qpolicies ;-)

> | > With a manpage I mean to document
> |
> | Is there any "man dccp"?
>
> Not yet. If you or someone else can find time to contribute towards a DCCP
> manpage, that would be just great. The best available information so far is
> on the OSDL pages for DCCP and Documentation/networking/dccp.txt.
>
But it's not in kernel sources? Then probably a new page would not be accepted 
as it would describe an experimental API. The above mentioned dccp.txt is 
probably the best place for now.

> I think there is a special maintainer for the kernel manpages, who could
> be emailed with a basic manpage. But ther ere is a similar problem - if the
> API changes frequently, then this requires to update the manpage
> accordingly.
>
I guess these would mostly be API additions, without any incompatible changes.

> As alternatives to documentation, there are for example providing
>  *running source code,
I will for sure be working on some apps to demonstrate how the new interface 
can be used. But first I need to create a simple server/client transmitting 
G.726 encoded voice over UDP/RTP (any hints on that?)...

>  * web pages or
Is there any official, publicly editable DCCP wiki? I'd rather not create yet 
another page...
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Tuesday 17 of June 2008, Gerrit Renker napisał:
> | In other words the basic question is: do we want to add new parameters to
> | existing qpolicies (then we need parameter discovery) or we don't want
> | new parameters (then we don't need information about parameters available
> | at runtime).
> |
> | Having defined the alternatives it's time to decide which is better. I,
> | of course, claim that mine (which is adding new parameters to existing
> | qpolicies). That's simply because I think that providing both
> | DCCP_SCM_TIMEOUT and DCCP_SCM_PRIORITY parameters may be useful. And I
> | don't see an obvoius way of achieving that goal with "new policy for new
> | parameter" approach.
>
> I agree that providing both parameters may be useful, but don't see this
> as a place of contradiction.
>
> In the kernel I think it is best to make it type-safe, i.e. no new
> parameters to already-defined policies. But I can't see how this would
> restrict the use.
> (...)
>
So we would need new policy for each new parameter, right? I somehow don't 
like it but it should work. You are right that this way runtime parameter 
discovery is not necessary. BTW, we will have a bit of a problem with naming 
qpolicies ;-)

> | > With a manpage I mean to document
> |
> | Is there any "man dccp"?
>
> Not yet. If you or someone else can find time to contribute towards a DCCP
> manpage, that would be just great. The best available information so far is
> on the OSDL pages for DCCP and Documentation/networking/dccp.txt.
>
But it's not in kernel sources? Then probably a new page would not be accepted 
as it would describe an experimental API. The above mentioned dccp.txt is 
probably the best place for now.

> I think there is a special maintainer for the kernel manpages, who could
> be emailed with a basic manpage. But ther ere is a similar problem - if the
> API changes frequently, then this requires to update the manpage
> accordingly.
>
I guess these would mostly be API additions, without any incompatible changes.

> As alternatives to documentation, there are for example providing
>  *running source code,
I will for sure be working on some apps to demonstrate how the new interface 
can be used. But first I need to create a simple server/client transmitting 
G.726 encoded voice over UDP/RTP (any hints on that?)...

>  * web pages or
Is there any official, publicly editable DCCP wiki? I'd rather not create yet 
another page...
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Randy.Dunlap]

On Tue, 17 Jun 2008, Tomasz Grobelny wrote:

> Dnia Tuesday 17 of June 2008, Gerrit Renker napisa?:
> > | In other words the basic question is: do we want to add new parameters to
> > | existing qpolicies (then we need parameter discovery) or we don't want
> > | new parameters (then we don't need information about parameters available
> > | at runtime).
> > |
> > | Having defined the alternatives it's time to decide which is better. I,
> > | of course, claim that mine (which is adding new parameters to existing
> > | qpolicies). That's simply because I think that providing both
> > | DCCP_SCM_TIMEOUT and DCCP_SCM_PRIORITY parameters may be useful. And I
> > | don't see an obvoius way of achieving that goal with "new policy for new
> > | parameter" approach.
> >
> > I agree that providing both parameters may be useful, but don't see this
> > as a place of contradiction.
> >
> > In the kernel I think it is best to make it type-safe, i.e. no new
> > parameters to already-defined policies. But I can't see how this would
> > restrict the use.
> > (...)
> >
> So we would need new policy for each new parameter, right? I somehow don't 
> like it but it should work. You are right that this way runtime parameter 
> discovery is not necessary. BTW, we will have a bit of a problem with naming 
> qpolicies ;-)
> 
> > | > With a manpage I mean to document
> > |
> > | Is there any "man dccp"?
> >
> > Not yet. If you or someone else can find time to contribute towards a DCCP
> > manpage, that would be just great. The best available information so far is
> > on the OSDL pages for DCCP and Documentation/networking/dccp.txt.
> >
> But it's not in kernel sources? Then probably a new page would not be accepted 
> as it would describe an experimental API. The above mentioned dccp.txt is 
> probably the best place for now.
> 
> > I think there is a special maintainer for the kernel manpages, who could
> > be emailed with a basic manpage. But ther ere is a similar problem - if the
> > API changes frequently, then this requires to update the manpage
> > accordingly.

Michael's contact info is at http://kernel.org/doc/man-pages/ .

> I guess these would mostly be API additions, without any incompatible changes.
> 
> > As alternatives to documentation, there are for example providing
> >  *running source code,
> I will for sure be working on some apps to demonstrate how the new interface 
> can be used. But first I need to create a simple server/client transmitting 
> G.726 encoded voice over UDP/RTP (any hints on that?)...
> 
> >  * web pages or
> Is there any official, publicly editable DCCP wiki? I'd rather not create yet 
> another page...

The Linux Foundation wiki is probably as close to official as it gets.

  http://www.linuxfoundation.org/en/Net:Main_Page

-- 
~Randy

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Randy.Dunlap]

On Tue, 17 Jun 2008, Tomasz Grobelny wrote:

> Dnia Tuesday 17 of June 2008, Gerrit Renker napisa?:
> > | In other words the basic question is: do we want to add new parameters to
> > | existing qpolicies (then we need parameter discovery) or we don't want
> > | new parameters (then we don't need information about parameters available
> > | at runtime).
> > |
> > | Having defined the alternatives it's time to decide which is better. I,
> > | of course, claim that mine (which is adding new parameters to existing
> > | qpolicies). That's simply because I think that providing both
> > | DCCP_SCM_TIMEOUT and DCCP_SCM_PRIORITY parameters may be useful. And I
> > | don't see an obvoius way of achieving that goal with "new policy for new
> > | parameter" approach.
> >
> > I agree that providing both parameters may be useful, but don't see this
> > as a place of contradiction.
> >
> > In the kernel I think it is best to make it type-safe, i.e. no new
> > parameters to already-defined policies. But I can't see how this would
> > restrict the use.
> > (...)
> >
> So we would need new policy for each new parameter, right? I somehow don't 
> like it but it should work. You are right that this way runtime parameter 
> discovery is not necessary. BTW, we will have a bit of a problem with naming 
> qpolicies ;-)
> 
> > | > With a manpage I mean to document
> > |
> > | Is there any "man dccp"?
> >
> > Not yet. If you or someone else can find time to contribute towards a DCCP
> > manpage, that would be just great. The best available information so far is
> > on the OSDL pages for DCCP and Documentation/networking/dccp.txt.
> >
> But it's not in kernel sources? Then probably a new page would not be accepted 
> as it would describe an experimental API. The above mentioned dccp.txt is 
> probably the best place for now.
> 
> > I think there is a special maintainer for the kernel manpages, who could
> > be emailed with a basic manpage. But ther ere is a similar problem - if the
> > API changes frequently, then this requires to update the manpage
> > accordingly.

Michael's contact info is at http://kernel.org/doc/man-pages/ .

> I guess these would mostly be API additions, without any incompatible changes.
> 
> > As alternatives to documentation, there are for example providing
> >  *running source code,
> I will for sure be working on some apps to demonstrate how the new interface 
> can be used. But first I need to create a simple server/client transmitting 
> G.726 encoded voice over UDP/RTP (any hints on that?)...
> 
> >  * web pages or
> Is there any official, publicly editable DCCP wiki? I'd rather not create yet 
> another page...

The Linux Foundation wiki is probably as close to official as it gets.

  http://www.linuxfoundation.org/en/Net:Main_Page

-- 
~Randy

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| > In the kernel I think it is best to make it type-safe, i.e. no new
| > parameters to already-defined policies. But I can't see how this would
| > restrict the use.
| > (...)
| >
| So we would need new policy for each new parameter, right? I somehow don't 
| like it but it should work. You are right that this way runtime parameter 
| discovery is not necessary. BTW, we will have a bit of a problem with naming 
| qpolicies ;-)
| 
Yes, not claiming that my suggestions were very good.

By the way, did you notice that the matrix was incomplete - timeout standalone
was missing, the corrected version would look something like

    +-------------+--------+-------------------+------------------+
    | Policy Name | Policy |         Presence of Parameters       |
    |             | ID#    | DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT |
    +-------------+--------+-------------------+------------------+
    | "simple     |   0    |        no         |        no        |
    | "prio"      |   1    |       YES         |        no        |
    | "timeout"   |   2?   |        no         |       YES        |
    | "timed-prio"|   3?   |       YES         |       YES        |
    +-------------+--------+-------------------+------------------+

There is a special trick for the aggregate "timed-prio" policy: it is
the logical-OR of the "prio" and "timeout" policy IDs. Perhaps composite
policy IDs could be defined in this way.


| I will for sure be working on some apps to demonstrate how the new interface 
| can be used. But first I need to create a simple server/client transmitting 
| G.726 encoded voice over UDP/RTP (any hints on that?)...
| 
Tommi Saviranta has been working on a DCCP port for SpeexComm:
	http://tuomas.kulve.fi/projects/speexcomm/
The port is available via SVN:
	svn co http://tuomas.kulve.fi/svn/speexcomm

Leandro Sales de Melo has developed a DCCP plugin for gstreamer and used
it with VoIP/speex. It comes with example applications for these:
https://garage.maemo.org/frs/?group_id)7
https://garage.maemo.org/projects/ephone
http://www.mail-archive.com/dccp@vger.kernel.org/msg03101.html

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

| > In the kernel I think it is best to make it type-safe, i.e. no new
| > parameters to already-defined policies. But I can't see how this would
| > restrict the use.
| > (...)
| >
| So we would need new policy for each new parameter, right? I somehow don't 
| like it but it should work. You are right that this way runtime parameter 
| discovery is not necessary. BTW, we will have a bit of a problem with naming 
| qpolicies ;-)
| 
Yes, not claiming that my suggestions were very good.

By the way, did you notice that the matrix was incomplete - timeout standalone
was missing, the corrected version would look something like

    +-------------+--------+-------------------+------------------+
    | Policy Name | Policy |         Presence of Parameters       |
    |             | ID#    | DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT |
    +-------------+--------+-------------------+------------------+
    | "simple     |   0    |        no         |        no        |
    | "prio"      |   1    |       YES         |        no        |
    | "timeout"   |   2?   |        no         |       YES        |
    | "timed-prio"|   3?   |       YES         |       YES        |
    +-------------+--------+-------------------+------------------+

There is a special trick for the aggregate "timed-prio" policy: it is
the logical-OR of the "prio" and "timeout" policy IDs. Perhaps composite
policy IDs could be defined in this way.


| I will for sure be working on some apps to demonstrate how the new interface 
| can be used. But first I need to create a simple server/client transmitting 
| G.726 encoded voice over UDP/RTP (any hints on that?)...
| 
Tommi Saviranta has been working on a DCCP port for SpeexComm:
	http://tuomas.kulve.fi/projects/speexcomm/
The port is available via SVN:
	svn co http://tuomas.kulve.fi/svn/speexcomm

Leandro Sales de Melo has developed a DCCP plugin for gstreamer and used
it with VoIP/speex. It comes with example applications for these:
https://garage.maemo.org/frs/?group_id=297
https://garage.maemo.org/projects/ephone
http://www.mail-archive.com/dccp@vger.kernel.org/msg03101.html

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Wednesday 18 of June 2008, Gerrit Renker napisa³:
> | > In the kernel I think it is best to make it type-safe, i.e. no new
> | > parameters to already-defined policies. But I can't see how this would
> | > restrict the use.
> | > (...)
> |
> | So we would need new policy for each new parameter, right? I somehow
> | don't like it but it should work. You are right that this way runtime
> | parameter discovery is not necessary. BTW, we will have a bit of a
> | problem with naming qpolicies ;-)
>
> Yes, not claiming that my suggestions were very good.
>
> By the way, did you notice that the matrix was incomplete - timeout
> standalone was missing, the corrected version would look something like
>
Well, I assumed that you did that on purpose because that would imply that we 
need more or less N policies for N parameters added one at a time. When we 
want separate policy for just timeout we end up with 2^N policies. And that 
would be just mad because the same effect can easily be achieved with setting 
priority to the same value on all packets.

>     +-------------+--------+-------------------+------------------+
>
>     | Policy Name | Policy |         Presence of Parameters       |
>     |
>     |             | ID#    | DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT |
>
>     +-------------+--------+-------------------+------------------+
>
>     | "simple     |   0    |        no         |        no        |
>     | "prio"      |   1    |       YES         |        no        |
>     | "timeout"   |   2?   |        no         |       YES        |
>     | "timed-prio"|   3?   |       YES         |       YES        |
>
>     +-------------+--------+-------------------+------------------+
>
> There is a special trick for the aggregate "timed-prio" policy: it is
> the logical-OR of the "prio" and "timeout" policy IDs. Perhaps composite
> policy IDs could be defined in this way.
>
Then we would have straight mapping between possible parameters and policy 
numbers. That is, effectively we would not set the policy number but request 
the capability of processing certain parameters, right? So that the 
application could specify 0, DCCP_SCM_PRIORITY, DCCP_SCM_TIMEOUT or 
DCCP_SCM_PRIORITY|DCCP_SCM_TIMEOUT as the policy ID?

Could be nice, but what happens if we have two policies with the same set of 
supported parameters? How do we differentiate them? In the above: how do we 
diffrentiate between simple policy (which doesn't have any parameters ever) 
and prio policy with no parameters (just because we don't need to provide any 
for one particular case)?

> | I will for sure be working on some apps to demonstrate how the new
> | interface can be used. But first I need to create a simple server/client
> | transmitting G.726 encoded voice over UDP/RTP (any hints on that?)...
>
> Tommi Saviranta has been working on a DCCP port for SpeexComm:
> 	http://tuomas.kulve.fi/projects/speexcomm/
> The port is available via SVN:
> 	svn co http://tuomas.kulve.fi/svn/speexcomm
>
> Leandro Sales de Melo has developed a DCCP plugin for gstreamer and used
> it with VoIP/speex. It comes with example applications for these:
> https://garage.maemo.org/frs/?group_id)7
> https://garage.maemo.org/projects/ephone
> http://www.mail-archive.com/dccp@vger.kernel.org/msg03101.html
> 
I'll have a look at these. It seems that GStreamer is the way to go. However, 
there is a minor glitch. GStreamer doesn't support a clean way of passing 
priority data between plugins, so the code will probably be a bit ugly.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Wednesday 18 of June 2008, Gerrit Renker napisał:
> | > In the kernel I think it is best to make it type-safe, i.e. no new
> | > parameters to already-defined policies. But I can't see how this would
> | > restrict the use.
> | > (...)
> |
> | So we would need new policy for each new parameter, right? I somehow
> | don't like it but it should work. You are right that this way runtime
> | parameter discovery is not necessary. BTW, we will have a bit of a
> | problem with naming qpolicies ;-)
>
> Yes, not claiming that my suggestions were very good.
>
> By the way, did you notice that the matrix was incomplete - timeout
> standalone was missing, the corrected version would look something like
>
Well, I assumed that you did that on purpose because that would imply that we 
need more or less N policies for N parameters added one at a time. When we 
want separate policy for just timeout we end up with 2^N policies. And that 
would be just mad because the same effect can easily be achieved with setting 
priority to the same value on all packets.

>     +-------------+--------+-------------------+------------------+
>
>     | Policy Name | Policy |         Presence of Parameters       |
>     |
>     |             | ID#    | DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT |
>
>     +-------------+--------+-------------------+------------------+
>
>     | "simple     |   0    |        no         |        no        |
>     | "prio"      |   1    |       YES         |        no        |
>     | "timeout"   |   2?   |        no         |       YES        |
>     | "timed-prio"|   3?   |       YES         |       YES        |
>
>     +-------------+--------+-------------------+------------------+
>
> There is a special trick for the aggregate "timed-prio" policy: it is
> the logical-OR of the "prio" and "timeout" policy IDs. Perhaps composite
> policy IDs could be defined in this way.
>
Then we would have straight mapping between possible parameters and policy 
numbers. That is, effectively we would not set the policy number but request 
the capability of processing certain parameters, right? So that the 
application could specify 0, DCCP_SCM_PRIORITY, DCCP_SCM_TIMEOUT or 
DCCP_SCM_PRIORITY|DCCP_SCM_TIMEOUT as the policy ID?

Could be nice, but what happens if we have two policies with the same set of 
supported parameters? How do we differentiate them? In the above: how do we 
diffrentiate between simple policy (which doesn't have any parameters ever) 
and prio policy with no parameters (just because we don't need to provide any 
for one particular case)?

> | I will for sure be working on some apps to demonstrate how the new
> | interface can be used. But first I need to create a simple server/client
> | transmitting G.726 encoded voice over UDP/RTP (any hints on that?)...
>
> Tommi Saviranta has been working on a DCCP port for SpeexComm:
> 	http://tuomas.kulve.fi/projects/speexcomm/
> The port is available via SVN:
> 	svn co http://tuomas.kulve.fi/svn/speexcomm
>
> Leandro Sales de Melo has developed a DCCP plugin for gstreamer and used
> it with VoIP/speex. It comes with example applications for these:
> https://garage.maemo.org/frs/?group_id=297
> https://garage.maemo.org/projects/ephone
> http://www.mail-archive.com/dccp@vger.kernel.org/msg03101.html
> 
I'll have a look at these. It seems that GStreamer is the way to go. However, 
there is a minor glitch. GStreamer doesn't support a clean way of passing 
priority data between plugins, so the code will probably be a bit ugly.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| > By the way, did you notice that the matrix was incomplete - timeout
| > standalone was missing, the corrected version would look something like
| >
| Well, I assumed that you did that on purpose because that would imply that we 
| need more or less N policies for N parameters added one at a time. When we 
| want separate policy for just timeout we end up with 2^N policies. And that 
| would be just mad because the same effect can easily be achieved with setting 
| priority to the same value on all packets.
| 
No it was just forgotten. 

With regard to below, given N parameters, 2^N is the number of all
order-independent combinations of 0..N parameters. E.g. for parameters A,B,C:
 * {}                 (no parameters at all)
 * {A} {B} {C}	      (non-composite: 1 parameter)
 * {A,B} {A,C} {B,C}  (composite of N-1 parameters)	
 * {A,B,C}            (composite of N   parameters)

which gives 2^3 = 8 cases. The empty set corresponds to the "simple" policy.

| >     +-------------+--------+-------------------+------------------+
| >     | Policy Name | Policy |         Presence of Parameters       |
| >     |
| >     |             | ID#    | DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT |
| >     +-------------+--------+-------------------+------------------+
| >     | "simple     |   0    |        no         |        no        |
| >     | "prio"      |   1    |       YES         |        no        |
| >     | "timeout"   |   2?   |        no         |       YES        |
| >     | "timed-prio"|   3?   |       YES         |       YES        |
| >
| >     +-------------+--------+-------------------+------------------+
| >
| > There is a special trick for the aggregate "timed-prio" policy: it is
| > the logical-OR of the "prio" and "timeout" policy IDs. Perhaps composite
| > policy IDs could be defined in this way.
| >
| Then we would have straight mapping between possible parameters and policy 
| numbers. That is, effectively we would not set the policy number but request 
| the capability of processing certain parameters, right? So that the 
| application could specify 0, DCCP_SCM_PRIORITY, DCCP_SCM_TIMEOUT or 
| DCCP_SCM_PRIORITY|DCCP_SCM_TIMEOUT as the policy ID?
| 
I think that this would make the 2^N mentioned by you above manageable.
We only need N parameters, but gain 2^N combinations practically "for free".

But such a bottom-up approach would not necessarily make sense, since
likely the policy will do a bit more work than just reacting to the
parameters it uses, which leads to the next point.

| Could be nice, but what happens if we have two policies with the same set of 
| supported parameters? How do we differentiate them? In the above: how do we 
| diffrentiate between simple policy (which doesn't have any parameters ever) 
| and prio policy with no parameters (just because we don't need to provide any 
| for one particular case)?
We could still encode the parameters in the policy ID, by splitting the
bitmask, e.g. the low 24 bits to encode parameters, and the high 8 bits
to encode the policies using the same combination of parameters.
Numbers depend on how many different parameters/policies to support:

 * e.g. using x = 32 bits, 
 * l: lower bits  corresponding to the number of parameters
 * h: higher bits; 2^h = number of policies with same parameters

It seems h may not need to be very high. How many policies with the
same parameters should we support -- 2/4/8/16 (corresponding to	h=1/2/3/4)?
That would still leave room for up to 28 different parameters.

| > Leandro Sales de Melo has developed a DCCP plugin for gstreamer and used
| > it with VoIP/speex. It comes with example applications for these:
| > https://garage.maemo.org/frs/?group_id)7
| > https://garage.maemo.org/projects/ephone
| > http://www.mail-archive.com/dccp@vger.kernel.org/msg03101.html
| > 
| I'll have a look at these. It seems that GStreamer is the way to go. However, 
| there is a minor glitch. GStreamer doesn't support a clean way of passing 
| priority data between plugins, so the code will probably be a bit ugly.
| -- 
It is probably best to ask Leandro directly as he knows the code well and has
done a lot of work on gstreamer.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

| > By the way, did you notice that the matrix was incomplete - timeout
| > standalone was missing, the corrected version would look something like
| >
| Well, I assumed that you did that on purpose because that would imply that we 
| need more or less N policies for N parameters added one at a time. When we 
| want separate policy for just timeout we end up with 2^N policies. And that 
| would be just mad because the same effect can easily be achieved with setting 
| priority to the same value on all packets.
| 
No it was just forgotten. 

With regard to below, given N parameters, 2^N is the number of all
order-independent combinations of 0..N parameters. E.g. for parameters A,B,C:
 * {}                 (no parameters at all)
 * {A} {B} {C}	      (non-composite: 1 parameter)
 * {A,B} {A,C} {B,C}  (composite of N-1 parameters)	
 * {A,B,C}            (composite of N   parameters)

which gives 2^3 = 8 cases. The empty set corresponds to the "simple" policy.

| >     +-------------+--------+-------------------+------------------+
| >     | Policy Name | Policy |         Presence of Parameters       |
| >     |
| >     |             | ID#    | DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT |
| >     +-------------+--------+-------------------+------------------+
| >     | "simple     |   0    |        no         |        no        |
| >     | "prio"      |   1    |       YES         |        no        |
| >     | "timeout"   |   2?   |        no         |       YES        |
| >     | "timed-prio"|   3?   |       YES         |       YES        |
| >
| >     +-------------+--------+-------------------+------------------+
| >
| > There is a special trick for the aggregate "timed-prio" policy: it is
| > the logical-OR of the "prio" and "timeout" policy IDs. Perhaps composite
| > policy IDs could be defined in this way.
| >
| Then we would have straight mapping between possible parameters and policy 
| numbers. That is, effectively we would not set the policy number but request 
| the capability of processing certain parameters, right? So that the 
| application could specify 0, DCCP_SCM_PRIORITY, DCCP_SCM_TIMEOUT or 
| DCCP_SCM_PRIORITY|DCCP_SCM_TIMEOUT as the policy ID?
| 
I think that this would make the 2^N mentioned by you above manageable.
We only need N parameters, but gain 2^N combinations practically "for free".

But such a bottom-up approach would not necessarily make sense, since
likely the policy will do a bit more work than just reacting to the
parameters it uses, which leads to the next point.

| Could be nice, but what happens if we have two policies with the same set of 
| supported parameters? How do we differentiate them? In the above: how do we 
| diffrentiate between simple policy (which doesn't have any parameters ever) 
| and prio policy with no parameters (just because we don't need to provide any 
| for one particular case)?
We could still encode the parameters in the policy ID, by splitting the
bitmask, e.g. the low 24 bits to encode parameters, and the high 8 bits
to encode the policies using the same combination of parameters.
Numbers depend on how many different parameters/policies to support:

 * e.g. using x = 32 bits, 
 * l: lower bits  corresponding to the number of parameters
 * h: higher bits; 2^h = number of policies with same parameters

It seems h may not need to be very high. How many policies with the
same parameters should we support -- 2/4/8/16 (corresponding to	h=1/2/3/4)?
That would still leave room for up to 28 different parameters.

| > Leandro Sales de Melo has developed a DCCP plugin for gstreamer and used
| > it with VoIP/speex. It comes with example applications for these:
| > https://garage.maemo.org/frs/?group_id=297
| > https://garage.maemo.org/projects/ephone
| > http://www.mail-archive.com/dccp@vger.kernel.org/msg03101.html
| > 
| I'll have a look at these. It seems that GStreamer is the way to go. However, 
| there is a minor glitch. GStreamer doesn't support a clean way of passing 
| priority data between plugins, so the code will probably be a bit ugly.
| -- 
It is probably best to ask Leandro directly as he knows the code well and has
done a lot of work on gstreamer.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Thursday 19 of June 2008, Gerrit Renker napisa³:
> But such a bottom-up approach would not necessarily make sense, since
> likely the policy will do a bit more work than just reacting to the
> parameters it uses, which leads to the next point.
>
Agreed.

> | Could be nice, but what happens if we have two policies with the same set
> | of supported parameters? How do we differentiate them? In the above: how
> | do we diffrentiate between simple policy (which doesn't have any
> | parameters ever) and prio policy with no parameters (just because we
> | don't need to provide any for one particular case)?
>
> We could still encode the parameters in the policy ID, by splitting the
> bitmask, e.g. the low 24 bits to encode parameters, and the high 8 bits
> to encode the policies using the same combination of parameters.
>
Yes, technically we could do it this way. Encoding accepted parameters in 
policy ID would provide applications with means to check whether certain 
parameters are supported. But should we mix two IMO distinct concepts (policy 
behaviour and accepted parameters) in one bitfield? I'd rather have them 
separated.

Keeping policy IDs as they are and using a bitfield for just parameters could 
be a nice idea. It would certainly  simplify checking which parameters are 
supported - just a simple & and = would suffice.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Thursday 19 of June 2008, Gerrit Renker napisał:
> But such a bottom-up approach would not necessarily make sense, since
> likely the policy will do a bit more work than just reacting to the
> parameters it uses, which leads to the next point.
>
Agreed.

> | Could be nice, but what happens if we have two policies with the same set
> | of supported parameters? How do we differentiate them? In the above: how
> | do we diffrentiate between simple policy (which doesn't have any
> | parameters ever) and prio policy with no parameters (just because we
> | don't need to provide any for one particular case)?
>
> We could still encode the parameters in the policy ID, by splitting the
> bitmask, e.g. the low 24 bits to encode parameters, and the high 8 bits
> to encode the policies using the same combination of parameters.
>
Yes, technically we could do it this way. Encoding accepted parameters in 
policy ID would provide applications with means to check whether certain 
parameters are supported. But should we mix two IMO distinct concepts (policy 
behaviour and accepted parameters) in one bitfield? I'd rather have them 
separated.

Keeping policy IDs as they are and using a bitfield for just parameters could 
be a nice idea. It would certainly  simplify checking which parameters are 
supported - just a simple & and == would suffice.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| > We could still encode the parameters in the policy ID, by splitting the
| > bitmask, e.g. the low 24 bits to encode parameters, and the high 8 bits
| > to encode the policies using the same combination of parameters.
| >
| Yes, technically we could do it this way. Encoding accepted parameters in 
| policy ID would provide applications with means to check whether certain 
| parameters are supported. But should we mix two IMO distinct concepts (policy 
| behaviour and accepted parameters) in one bitfield? I'd rather have them 
| separated.
| 
Yes having them separate gives a clearer semantics. But it comes at a price - 
to retrieve the parameters, we need an extra function or lookup table. 

Maybe there is an elegant solution which allows to encode the required
parameters while keeping the semantics clear?

| Keeping policy IDs as they are and using a bitfield for just parameters could 
| be a nice idea. It would certainly  simplify checking which parameters are 
| supported - just a simple & and = would suffice.
| -- 
And it is fast, too.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

| > We could still encode the parameters in the policy ID, by splitting the
| > bitmask, e.g. the low 24 bits to encode parameters, and the high 8 bits
| > to encode the policies using the same combination of parameters.
| >
| Yes, technically we could do it this way. Encoding accepted parameters in 
| policy ID would provide applications with means to check whether certain 
| parameters are supported. But should we mix two IMO distinct concepts (policy 
| behaviour and accepted parameters) in one bitfield? I'd rather have them 
| separated.
| 
Yes having them separate gives a clearer semantics. But it comes at a price - 
to retrieve the parameters, we need an extra function or lookup table. 

Maybe there is an elegant solution which allows to encode the required
parameters while keeping the semantics clear?

| Keeping policy IDs as they are and using a bitfield for just parameters could 
| be a nice idea. It would certainly  simplify checking which parameters are 
| supported - just a simple & and == would suffice.
| -- 
And it is fast, too.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Monday 23 of June 2008, Gerrit Renker napisa³:
> | > We could still encode the parameters in the policy ID, by splitting the
> | > bitmask, e.g. the low 24 bits to encode parameters, and the high 8 bits
> | > to encode the policies using the same combination of parameters.
> |
> | Yes, technically we could do it this way. Encoding accepted parameters in
> | policy ID would provide applications with means to check whether certain
> | parameters are supported. But should we mix two IMO distinct concepts
> | (policy behaviour and accepted parameters) in one bitfield? I'd rather
> | have them separated.
>
> Yes having them separate gives a clearer semantics. But it comes at a price
> - to retrieve the parameters, we need an extra function or lookup table.
>
An additional bitfield in dccp_qpolicy_operations should do it when it comes 
to storing that information. When it comes to retrieving see next point...

> Maybe there is an elegant solution which allows to encode the required
> parameters while keeping the semantics clear?
>
What about something like:
	setsockopt(sockfd, DCCP_SOCKOPT_QPOLICY_ID, DCCPQ_POLICY_PRIO);
to choose policy (exactly as it is now) and a new function to ensure that the 
kernel understands parameters:
	setsockopt(sockfd, DCCP_SOCKOPT_QPOLICY_PARAMS, DCCP_SCM_PRIORITY | 
DCCP_SCM_TIMEOUT);

The second call would return an error if the kernel does not know anything 
about DCCP_SCM_TIMEOUT (or a choosen policy does not support it). This would 
have the additional benefit (over similar getsockopt) that the kernel will be 
able to optimize its behaviour knowning the set of parameters that will be 
used.

What do you think about such an interface?
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Monday 23 of June 2008, Gerrit Renker napisał:
> | > We could still encode the parameters in the policy ID, by splitting the
> | > bitmask, e.g. the low 24 bits to encode parameters, and the high 8 bits
> | > to encode the policies using the same combination of parameters.
> |
> | Yes, technically we could do it this way. Encoding accepted parameters in
> | policy ID would provide applications with means to check whether certain
> | parameters are supported. But should we mix two IMO distinct concepts
> | (policy behaviour and accepted parameters) in one bitfield? I'd rather
> | have them separated.
>
> Yes having them separate gives a clearer semantics. But it comes at a price
> - to retrieve the parameters, we need an extra function or lookup table.
>
An additional bitfield in dccp_qpolicy_operations should do it when it comes 
to storing that information. When it comes to retrieving see next point...

> Maybe there is an elegant solution which allows to encode the required
> parameters while keeping the semantics clear?
>
What about something like:
	setsockopt(sockfd, DCCP_SOCKOPT_QPOLICY_ID, DCCPQ_POLICY_PRIO);
to choose policy (exactly as it is now) and a new function to ensure that the 
kernel understands parameters:
	setsockopt(sockfd, DCCP_SOCKOPT_QPOLICY_PARAMS, DCCP_SCM_PRIORITY | 
DCCP_SCM_TIMEOUT);

The second call would return an error if the kernel does not know anything 
about DCCP_SCM_TIMEOUT (or a choosen policy does not support it). This would 
have the additional benefit (over similar getsockopt) that the kernel will be 
able to optimize its behaviour knowning the set of parameters that will be 
used.

What do you think about such an interface?
-- 
Regards,
Tomasz Grobelny

[manpages]: First stab at a udplite(7) manpage

[Gerrit Renker]

[-- Attachment #1: Type: text/plain, Size: 382 bytes --]

Hi Michael (cc-ed to list),

as per earlier conversation, I have sat down and assembled a udplite.7
manpage. I have checked it against the conventions (in particular spelling)
mentioned in man-pages(7) and it seems ok.

Since I am rather a groff-newbie, I'd welcome suggestions to improve the
format, the content seems now stable (after a few iterations).

With best regards
Gerrit

[-- Attachment #2: udplite.7 --]
[-- Type: text/plain, Size: 3625 bytes --]

.TH UDPLITE  7 2008-06-23 "Linux" "Linux Programmer's Manual"

.SH NAME
udplite \- Lightweight User Datagram Protocol
.SH SYNOPSIS
.B #include <sys/socket.h>
.br
.\" FIXME: see #defines under `BUGS',
.\"        when glibc supports this, add 
.\"        #include <netinet/udplite.h>
.sp
.B s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
.SH DESCRIPTION
This is an implementation of the Lightweight User Datagram Protocol
(UDP-Lite), as described in RFC\ 3828.

UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length
checksums. This has advantages for some types of multimedia transport,
as it allows to reuse partly damaged frames (with few bit errors).

The variable-length checksum coverage is set via a
.BR setsockopt (2)
option. If this option is not set, the only difference to UDP is
in using a different IP protocol identifier (IANA number 136).

The UDP-Lite implementation is a full extension of
.BR udp (7),
i.e.  it shares the same API and API behaviour, and in addition
offers two socket options to control the checksum coverage.
.SS "Address Format"
UDP-Litev4 uses the
.I sockaddr_in
address format described in
.BR ip (7).
UDP-Litev6 uses the
.I sockaddr_in6
address format described in
.BR ipv6 (7).
.SS "Socket Options"
To set or get a UDP-Lite socket option, call
.BR getsockopt (2)
to read or
.BR setsockopt (2)
to write the option with the option level argument set to
.BR IPPROTO_UDPLITE .
In addition, all 
.B IPPROTO_UDP
socket options are valid on a UDP-Lite socket. See
.BR udp (7)
for more information.

The following two options are specific to UDP-Lite.
.TP
.BR UDPLITE_SEND_CSCOV
This option sets the sender checksum coverage and takes an 
.B int
as argument, with a checksum coverage value in the range 0..2^16-1.

A value of 0 means that always the entire datagram is covered,
values from 1-7 are illegal (RFC\ 3828, 3.1) and are rounded up to
the minimum coverage of 8.

With regard to IPv6 jumbograms (RFC\ 2675), the UDP-Litev6 checksum
coverage is limited to the first 2^16-1 octets, as per RFC\ 3828, 3.5.
Higher values are therefore not supported.
.TP
.BR UDPLITE_RECV_CSCOV
This is the receiver-side analogue and uses uses the same argument format
and value range as
.BR UDPLITE_SEND_CSCOV .
This option is not required to enable traffic with partial checksum 
coverage. Its function is that of a traffic filter: when enabled, it
instructs the kernel to drop all packets which have a coverage
.I less
than the specified coverage value.
.\" FIXME: SO_NO_CHECK exists and is supported by UDPv4, but is
.\" commented out in socket(7), hence also here ???
.\".PP
.\"Since UDP-Lite mandates checksums, checksumming can not be disabled 
.\"via the
.\".B SO_NO_CHECK
.\"option from 
.\".BR socket (7).
.SH ERRORS
All errors documented for
.BR udp (7)
may be returned. UDP-Lite does not add further errors. When the value of
.B UDPLITE_RECV_CSCOV
exceeds the actual coverage, incoming packets are silently dropped,
but may generate a warning message in the system log.
.SH BUGS
.\" FIXME: remove this section once glibc supports UDP-Lite
Where glibc support is missing, the following defintions are needed:
.sp
.br
#define IPPROTO_UDPLITE     136
.br
.\" The following two are defined in the kernel in linux/net/udplite.h
#define UDPLITE_SEND_CSCOV  10
.br
#define UDPLITE_RECV_CSCOV  11
.SH FILES
.I /proc/net/snmp 
.br
.IR /proc/net/snmp6
.SH VERSIONS
UDP-Litev4/v6 first appeared in Linux 2.6.20.
.SH "SEE ALSO"
.BR udp (7),
.BR ip (7),
.BR ipv6 (7),
.BR socket (7)

RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite)
.br
.I Documentation/networking/udplite.txt

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| > Yes having them separate gives a clearer semantics. But it comes at a price
| > - to retrieve the parameters, we need an extra function or lookup table.
| >
| An additional bitfield in dccp_qpolicy_operations should do it when it comes 
| to storing that information. When it comes to retrieving see next point...
| 
| > Maybe there is an elegant solution which allows to encode the required
| > parameters while keeping the semantics clear?
| >
| What about something like:
| 	setsockopt(sockfd, DCCP_SOCKOPT_QPOLICY_ID, DCCPQ_POLICY_PRIO);
| to choose policy (exactly as it is now) and a new function to ensure that the 
| kernel understands parameters:
| 	setsockopt(sockfd, DCCP_SOCKOPT_QPOLICY_PARAMS, DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT);
| 
| The second call would return an error if the kernel does not know anything 
| about DCCP_SCM_TIMEOUT (or a choosen policy does not support it). This would 
| have the additional benefit (over similar getsockopt) that the kernel will be 
| able to optimize its behaviour knowning the set of parameters that will be 
| used.
| 
| What do you think about such an interface?
| -- 
In both solutions there is a need to maintain an integrity constraint
between the qpolicy ID and the set of parameters that the qpolicy uses.

With the bitmask approach this constraint is expressed only once, when
the policy is defined in the source file.

With the socket approach, the constraint needs to be expressed each time
the policy is used.

I don't know your reservations against the bitmask approach (other than the
semantics), but I find having to define the parameters each time the qpolicy
is used cumbersome, and it can also be a source of errors.

Gerrit

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

| > Yes having them separate gives a clearer semantics. But it comes at a price
| > - to retrieve the parameters, we need an extra function or lookup table.
| >
| An additional bitfield in dccp_qpolicy_operations should do it when it comes 
| to storing that information. When it comes to retrieving see next point...
| 
| > Maybe there is an elegant solution which allows to encode the required
| > parameters while keeping the semantics clear?
| >
| What about something like:
| 	setsockopt(sockfd, DCCP_SOCKOPT_QPOLICY_ID, DCCPQ_POLICY_PRIO);
| to choose policy (exactly as it is now) and a new function to ensure that the 
| kernel understands parameters:
| 	setsockopt(sockfd, DCCP_SOCKOPT_QPOLICY_PARAMS, DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT);
| 
| The second call would return an error if the kernel does not know anything 
| about DCCP_SCM_TIMEOUT (or a choosen policy does not support it). This would 
| have the additional benefit (over similar getsockopt) that the kernel will be 
| able to optimize its behaviour knowning the set of parameters that will be 
| used.
| 
| What do you think about such an interface?
| -- 
In both solutions there is a need to maintain an integrity constraint
between the qpolicy ID and the set of parameters that the qpolicy uses.

With the bitmask approach this constraint is expressed only once, when
the policy is defined in the source file.

With the socket approach, the constraint needs to be expressed each time
the policy is used.

I don't know your reservations against the bitmask approach (other than the
semantics), but I find having to define the parameters each time the qpolicy
is used cumbersome, and it can also be a source of errors.

Gerrit

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Wednesday 25 of June 2008, Gerrit Renker napisa³:
> | > Yes having them separate gives a clearer semantics. But it comes at a
> | > price - to retrieve the parameters, we need an extra function or lookup
> | > table.
> |
> | An additional bitfield in dccp_qpolicy_operations should do it when it
> | comes to storing that information. When it comes to retrieving see next
> | point...
> |
> | > Maybe there is an elegant solution which allows to encode the required
> | > parameters while keeping the semantics clear?
> |
> | What about something like:
> | 	setsockopt(sockfd, DCCP_SOCKOPT_QPOLICY_ID, DCCPQ_POLICY_PRIO);
> | to choose policy (exactly as it is now) and a new function to ensure that
> | the kernel understands parameters:
> | 	setsockopt(sockfd, DCCP_SOCKOPT_QPOLICY_PARAMS, DCCP_SCM_PRIORITY |
> | DCCP_SCM_TIMEOUT);
> |
> | The second call would return an error if the kernel does not know
> | anything about DCCP_SCM_TIMEOUT (or a choosen policy does not support
> | it). This would have the additional benefit (over similar getsockopt)
> | that the kernel will be able to optimize its behaviour knowning the set
> | of parameters that will be used.
> |
> | What do you think about such an interface?
> | --
>
> In both solutions there is a need to maintain an integrity constraint
> between the qpolicy ID and the set of parameters that the qpolicy uses.
>
It is always the case, either explicit (as I propose) or implicit (when it 
would be a part of policy id).

> With the bitmask approach this constraint is expressed only once, when
> the policy is defined in the source file.
>
In what I propose it would also be defined once. Instead of:
	[DCCPQ_POLICY_PRIO] = {
		.push	= qpolicy_simple_push,
		.full	= qpolicy_prio_full,
		.top	= qpolicy_prio_best_skb,
	},
we would simply have:
	[DCCPQ_POLICY_PRIO] = {
		.push	= qpolicy_simple_push,
		.full	= qpolicy_prio_full,
		.top	= qpolicy_prio_best_skb,
		.params = DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT,
	},
Doesn't seem complicated, does it?

> With the socket approach, the constraint needs to be expressed each time
> the policy is used.
>
Yes. Two points:
1. The other option is /proc I guess... would that be better? I think not 
(even though I had other optinion on this subject earlier).
2. I think that it is actually good to enforce on application developers the 
need to declare which parameters they want to use. This way they almost 
cannot do it wrong.

> I don't know your reservations against the bitmask approach (other than the
> semantics), but I find having to define the parameters each time the
> qpolicy is used cumbersome, and it can also be a source of errors.
>
The bitmask approach is ok but I view combining parameters with policy id 
counterintuitive.

To make things clear: we both agree that the application should be able to get 
information if the parameters it wants to use are supported by the kernel 
it's running on, right?

The place where we differ is that you would prefer to have:
setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_POLICY_PRIO|(DCCP_SCM_PRIORITY<<8));

and I would like to have:
setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_POLICY_PRIO);
setsockopt(sockfd, DCCP_POLICY_PARAMS, DCCP_SCM_PRIORITY);

Is that right?
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Wednesday 25 of June 2008, Gerrit Renker napisał:
> | > Yes having them separate gives a clearer semantics. But it comes at a
> | > price - to retrieve the parameters, we need an extra function or lookup
> | > table.
> |
> | An additional bitfield in dccp_qpolicy_operations should do it when it
> | comes to storing that information. When it comes to retrieving see next
> | point...
> |
> | > Maybe there is an elegant solution which allows to encode the required
> | > parameters while keeping the semantics clear?
> |
> | What about something like:
> | 	setsockopt(sockfd, DCCP_SOCKOPT_QPOLICY_ID, DCCPQ_POLICY_PRIO);
> | to choose policy (exactly as it is now) and a new function to ensure that
> | the kernel understands parameters:
> | 	setsockopt(sockfd, DCCP_SOCKOPT_QPOLICY_PARAMS, DCCP_SCM_PRIORITY |
> | DCCP_SCM_TIMEOUT);
> |
> | The second call would return an error if the kernel does not know
> | anything about DCCP_SCM_TIMEOUT (or a choosen policy does not support
> | it). This would have the additional benefit (over similar getsockopt)
> | that the kernel will be able to optimize its behaviour knowning the set
> | of parameters that will be used.
> |
> | What do you think about such an interface?
> | --
>
> In both solutions there is a need to maintain an integrity constraint
> between the qpolicy ID and the set of parameters that the qpolicy uses.
>
It is always the case, either explicit (as I propose) or implicit (when it 
would be a part of policy id).

> With the bitmask approach this constraint is expressed only once, when
> the policy is defined in the source file.
>
In what I propose it would also be defined once. Instead of:
	[DCCPQ_POLICY_PRIO] = {
		.push	= qpolicy_simple_push,
		.full	= qpolicy_prio_full,
		.top	= qpolicy_prio_best_skb,
	},
we would simply have:
	[DCCPQ_POLICY_PRIO] = {
		.push	= qpolicy_simple_push,
		.full	= qpolicy_prio_full,
		.top	= qpolicy_prio_best_skb,
		.params = DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT,
	},
Doesn't seem complicated, does it?

> With the socket approach, the constraint needs to be expressed each time
> the policy is used.
>
Yes. Two points:
1. The other option is /proc I guess... would that be better? I think not 
(even though I had other optinion on this subject earlier).
2. I think that it is actually good to enforce on application developers the 
need to declare which parameters they want to use. This way they almost 
cannot do it wrong.

> I don't know your reservations against the bitmask approach (other than the
> semantics), but I find having to define the parameters each time the
> qpolicy is used cumbersome, and it can also be a source of errors.
>
The bitmask approach is ok but I view combining parameters with policy id 
counterintuitive.

To make things clear: we both agree that the application should be able to get 
information if the parameters it wants to use are supported by the kernel 
it's running on, right?

The place where we differ is that you would prefer to have:
setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_POLICY_PRIO|(DCCP_SCM_PRIORITY<<8));

and I would like to have:
setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_POLICY_PRIO);
setsockopt(sockfd, DCCP_POLICY_PARAMS, DCCP_SCM_PRIORITY);

Is that right?
-- 
Regards,
Tomasz Grobelny

Re: [manpages]: First stab at a udplite(7) manpage

[Michael Kerrisk]

Hi Gerrit,

On Tue, Jun 24, 2008 at 3:36 PM, Gerrit Renker <gerrit-VsoRXqaLlyfQzY9nttDBhA@public.gmane.org> wrote:
> Hi Michael (cc-ed to list),
>
> as per earlier conversation, I have sat down and assembled a udplite.7
> manpage.

Thanks for that!

> I have checked it against the conventions (in particular spelling)
> mentioned in man-pages(7) and it seems ok.

Yes, it looks good.

> Since I am rather a groff-newbie, I'd welcome suggestions to improve the
> format, the content seems now stable (after a few iterations).

The groff was fine.  I made a few light edits to the page.  I also
added some comments to the page with some "FIXME(gr)" pointing to
places where I think some work is needed.  (I will later pick up the
FIXMEs you had already put in the page, when the glibc support
appears.)  Could you take a look at these?  The modified page is
inline below.

Thanks,

Michael

==============
.\" FIXME(gr) we need a license for this page.
.\" The one I tend to favor is shown in the capabilities.7 page,
.\" but others are also used in man-pages (e.g., GPL, BSD).
.TH UDPLITE  7 2008-06-23 "Linux" "Linux Programmer's Manual"
.SH NAME
udplite \- Lightweight User Datagram Protocol
.SH SYNOPSIS
.B #include <sys/socket.h>
.br
.\" FIXME: see #defines under `BUGS',
.\"        when glibc supports this, add
.\"        #include <netinet/udplite.h>
.sp
.B s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
.SH DESCRIPTION
This is an implementation of the Lightweight User Datagram Protocol
(UDP-Lite), as described in RFC\ 3828.

UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length
checksums.
This has advantages for some types of multimedia transport,
since it makes it possible to reuse partly damaged frames
(with few bit errors).
.\" FIXME(gr) is "reuse" the right word in the previous sentence?
.\" Reading the RFC suggests to me that a better wording might be:
.\"
.\" This has advantages for some types of multimedia transport that
.\" may be able to make use of slightly damaged datagrams,
.\" rather than having them discarded by lower layer protocols.

The variable-length checksum coverage is set via a
.BR setsockopt (2)
option.
If this option is not set, the only difference to UDP is
in using a different IP protocol identifier (IANA number 136).

The UDP-Lite implementation is a full extension of
.BR udp (7),
i.e., it shares the same API and API behaviour, and in addition
offers two socket options to control the checksum coverage.
.SS "Address Format"
UDP-Litev4 uses the
.I sockaddr_in
address format described in
.BR ip (7).
UDP-Litev6 uses the
.I sockaddr_in6
address format described in
.BR ipv6 (7).
.SS "Socket Options"
To set or get a UDP-Lite socket option, call
.BR getsockopt (2)
to read or
.BR setsockopt (2)
to write the option with the option level argument set to
.BR IPPROTO_UDPLITE .
In addition, all
.B IPPROTO_UDP
socket options are valid on a UDP-Lite socket.
See
.BR udp (7)
for more information.

The following two options are specific to UDP-Lite.
.TP
.BR UDPLITE_SEND_CSCOV
This option sets the sender checksum coverage and takes an
.B int
as argument, with a checksum coverage value in the range 0..2^16-1.

A value of 0 means that the entire datagram is always covered,
values from 1-7 are illegal (RFC\ 3828, 3.1) and are rounded up to
the minimum coverage of 8.

With regard to IPv6 jumbograms (RFC\ 2675), the UDP-Litev6 checksum
coverage is limited to the first 2^16-1 octets, as per RFC\ 3828, 3.5.
Higher values are therefore not supported.
.\" FIXME(gr) If higher values are specified, what happens?
.\" If they are silently ignored, probably we should explicitly
.\" say so here.
.TP
.BR UDPLITE_RECV_CSCOV
This is the receiver-side analogue and uses uses the same argument format
and value range as
.BR UDPLITE_SEND_CSCOV .
This option is not required to enable traffic with partial checksum
coverage.
Its function is that of a traffic filter: when enabled, it
instructs the kernel to drop all packets which have a coverage
.I less
than the specified coverage value.
.\" FIXME: SO_NO_CHECK exists and is supported by UDPv4, but is
.\" commented out in socket(7), hence also here ???
.\".PP
.\"Since UDP-Lite mandates checksums, checksumming can not be disabled
.\"via the
.\".B SO_NO_CHECK
.\"option from
.\".BR socket (7).
.SH ERRORS
All errors documented for
.BR udp (7)
may be returned.
UDP-Lite does not add further errors.
When the value of
.B UDPLITE_RECV_CSCOV
exceeds the actual coverage, incoming packets are silently dropped,
but may generate a warning message in the system log.
.SH BUGS
.\" FIXME: remove this section once glibc supports UDP-Lite
Where glibc support is missing, the following definitions are needed:
.in +4n
.nf

#define IPPROTO_UDPLITE     136
.\" The following two are defined in the kernel in linux/net/udplite.h
#define UDPLITE_SEND_CSCOV  10
#define UDPLITE_RECV_CSCOV  11
.fi
.in
.SH FILES
.I /proc/net/snmp
.br
.IR /proc/net/snmp6
.\" FIXME(gr)
.\" Could you add some discussion of the UDPLITE-specific
.\" info in these files?
.SH VERSIONS
UDP-Litev4/v6 first appeared in Linux 2.6.20.
.SH "SEE ALSO"
.BR udp (7),
.BR ip (7),
.BR ipv6 (7),
.BR socket (7)

RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite)
.br
.I Documentation/networking/udplite.txt
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [manpages]: First stab at a udplite(7) manpage

[Gerrit Renker]

| 
| The groff was fine.  I made a few light edits to the page.  I also
| added some comments to the page with some "FIXME(gr)" pointing to
| places where I think some work is needed.  
Thanks a lot for the review. It was particularly useful since it brought
to light an unresolved issue: when the coverage > 65535, then unexpected
things will happen since the internal fields are u16 and the
setsockopt() argument is `int'.

Will submit a bug-fix to netdev and resubmit the updated manpage when this
issue has been resolved.

Gerrit

| 
| ==============
| .\" FIXME(gr) we need a license for this page.
| .\" The one I tend to favor is shown in the capabilities.7 page,
| .\" but others are also used in man-pages (e.g., GPL, BSD).
| .TH UDPLITE  7 2008-06-23 "Linux" "Linux Programmer's Manual"
| .SH NAME
| udplite \- Lightweight User Datagram Protocol
| .SH SYNOPSIS
| .B #include <sys/socket.h>
| .br
| .\" FIXME: see #defines under `BUGS',
| .\"        when glibc supports this, add
| .\"        #include <netinet/udplite.h>
| .sp
| .B s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
| .SH DESCRIPTION
| This is an implementation of the Lightweight User Datagram Protocol
| (UDP-Lite), as described in RFC\ 3828.
| 
| UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length
| checksums.
| This has advantages for some types of multimedia transport,
| since it makes it possible to reuse partly damaged frames
| (with few bit errors).
| .\" FIXME(gr) is "reuse" the right word in the previous sentence?
| .\" Reading the RFC suggests to me that a better wording might be:
| .\"
| .\" This has advantages for some types of multimedia transport that
| .\" may be able to make use of slightly damaged datagrams,
| .\" rather than having them discarded by lower layer protocols.
| 
| The variable-length checksum coverage is set via a
| .BR setsockopt (2)
| option.
| If this option is not set, the only difference to UDP is
| in using a different IP protocol identifier (IANA number 136).
| 
| The UDP-Lite implementation is a full extension of
| .BR udp (7),
| i.e., it shares the same API and API behaviour, and in addition
| offers two socket options to control the checksum coverage.
| .SS "Address Format"
| UDP-Litev4 uses the
| .I sockaddr_in
| address format described in
| .BR ip (7).
| UDP-Litev6 uses the
| .I sockaddr_in6
| address format described in
| .BR ipv6 (7).
| .SS "Socket Options"
| To set or get a UDP-Lite socket option, call
| .BR getsockopt (2)
| to read or
| .BR setsockopt (2)
| to write the option with the option level argument set to
| .BR IPPROTO_UDPLITE .
| In addition, all
| .B IPPROTO_UDP
| socket options are valid on a UDP-Lite socket.
| See
| .BR udp (7)
| for more information.
| 
| The following two options are specific to UDP-Lite.
| .TP
| .BR UDPLITE_SEND_CSCOV
| This option sets the sender checksum coverage and takes an
| .B int
| as argument, with a checksum coverage value in the range 0..2^16-1.
| 
| A value of 0 means that the entire datagram is always covered,
| values from 1-7 are illegal (RFC\ 3828, 3.1) and are rounded up to
| the minimum coverage of 8.
| 
| With regard to IPv6 jumbograms (RFC\ 2675), the UDP-Litev6 checksum
| coverage is limited to the first 2^16-1 octets, as per RFC\ 3828, 3.5.
| Higher values are therefore not supported.
| .\" FIXME(gr) If higher values are specified, what happens?
| .\" If they are silently ignored, probably we should explicitly
| .\" say so here.
| .TP
| .BR UDPLITE_RECV_CSCOV
| This is the receiver-side analogue and uses uses the same argument format
| and value range as
| .BR UDPLITE_SEND_CSCOV .
| This option is not required to enable traffic with partial checksum
| coverage.
| Its function is that of a traffic filter: when enabled, it
| instructs the kernel to drop all packets which have a coverage
| .I less
| than the specified coverage value.
| .\" FIXME: SO_NO_CHECK exists and is supported by UDPv4, but is
| .\" commented out in socket(7), hence also here ???
| .\".PP
| .\"Since UDP-Lite mandates checksums, checksumming can not be disabled
| .\"via the
| .\".B SO_NO_CHECK
| .\"option from
| .\".BR socket (7).
| .SH ERRORS
| All errors documented for
| .BR udp (7)
| may be returned.
| UDP-Lite does not add further errors.
| When the value of
| .B UDPLITE_RECV_CSCOV
| exceeds the actual coverage, incoming packets are silently dropped,
| but may generate a warning message in the system log.
| .SH BUGS
| .\" FIXME: remove this section once glibc supports UDP-Lite
| Where glibc support is missing, the following definitions are needed:
| .in +4n
| .nf
| 
| #define IPPROTO_UDPLITE     136
| .\" The following two are defined in the kernel in linux/net/udplite.h
| #define UDPLITE_SEND_CSCOV  10
| #define UDPLITE_RECV_CSCOV  11
| .fi
| .in
| .SH FILES
| .I /proc/net/snmp
| .br
| .IR /proc/net/snmp6
| .\" FIXME(gr)
| .\" Could you add some discussion of the UDPLITE-specific
| .\" info in these files?
| .SH VERSIONS
| UDP-Litev4/v6 first appeared in Linux 2.6.20.
| .SH "SEE ALSO"
| .BR udp (7),
| .BR ip (7),
| .BR ipv6 (7),
| .BR socket (7)
| 
| RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite)
| .br
| .I Documentation/networking/udplite.txt
| 

-- 
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| > With the bitmask approach this constraint is expressed only once, when
| > the policy is defined in the source file.
| >
| In what I propose it would also be defined once. Instead of:
| 	[DCCPQ_POLICY_PRIO] = {
| 		.push	= qpolicy_simple_push,
| 		.full	= qpolicy_prio_full,
| 		.top	= qpolicy_prio_best_skb,
| 	},
| we would simply have:
| 	[DCCPQ_POLICY_PRIO] = {
| 		.push	= qpolicy_simple_push,
| 		.full	= qpolicy_prio_full,
| 		.top	= qpolicy_prio_best_skb,
| 		.params = DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT,
| 	},
| Doesn't seem complicated, does it?
| 
... and is also simpler than the bitmask approach. Very good idea: let's use this.


| > With the socket approach, the constraint needs to be expressed each time
| > the policy is used.
| >
| Yes. Two points:
| 1. The other option is /proc I guess... would that be better? I think not 
| (even though I had other optinion on this subject earlier).
Why put so much effort into this? All that is required is to refuse to
accept nonsensical parameters.

| 2. I think that it is actually good to enforce on application developers the 
| need to declare which parameters they want to use. This way they almost 
| cannot do it wrong.
| 
I don't agree: such a safety-net will only annoy good programmers who understand
what they are doing. And it will not help bad programmers much, since their problems
lie elsewhere. 

Further, the protection is not a strong one: nothing stops the user from first
declaring parameters X/Y and then supply something completely different.

| To make things clear: we both agree that the application should be able to get 
| information if the parameters it wants to use are supported by the kernel 
| it's running on, right?
| 
That is the central point. What we agree on is that that the policy should validate
the parameters that the user supplies via cmsg. We don't need the bitmask approach,
and with your suggested solution we have a mapping (.params field) between parameters
and policy IDs.

Which is sufficient to find out which parameters are acceptable for a policy.

| The place where we differ is that you would prefer to have:
| setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_POLICY_PRIO|(DCCP_SCM_PRIORITY<<8));
| 
| and I would like to have:
| setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_POLICY_PRIO);
| setsockopt(sockfd, DCCP_POLICY_PARAMS, DCCP_SCM_PRIORITY);
| 
| Is that right?
| -- 
Not quite. The first is just one way of relating policy IDs and parameters. First, as
above, I prefer your approach of using a .params field because it is simpler.    

With regard to the second point, I don't like the DCCP_POLICY_PARAMS socket option
since it does not prevent the user from using nonsensical parameters.

To summarise, what we have so far is:
 * qpolicy parameters are declared as disjoint bit values so that they can
   be or-ed together and tested with `&'/`=' operations;
 * the qpol_table gets a new (u32) field to keep the list of parameters
   that a policy accepts;
 * dccp_msghdr_parse() (net/dccp/proto.c) calls a qpolicy check routine to see
   if cmsg->cmsg_type is a parameter which is allowed by the  current qpolicy
 * if the parameter is not mentioned in the `.params' field of the qpol_table,
   dccp_msghdr_parse() returns -EINVAL.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Gerrit Renker]

| > With the bitmask approach this constraint is expressed only once, when
| > the policy is defined in the source file.
| >
| In what I propose it would also be defined once. Instead of:
| 	[DCCPQ_POLICY_PRIO] = {
| 		.push	= qpolicy_simple_push,
| 		.full	= qpolicy_prio_full,
| 		.top	= qpolicy_prio_best_skb,
| 	},
| we would simply have:
| 	[DCCPQ_POLICY_PRIO] = {
| 		.push	= qpolicy_simple_push,
| 		.full	= qpolicy_prio_full,
| 		.top	= qpolicy_prio_best_skb,
| 		.params = DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT,
| 	},
| Doesn't seem complicated, does it?
| 
... and is also simpler than the bitmask approach. Very good idea: let's use this.


| > With the socket approach, the constraint needs to be expressed each time
| > the policy is used.
| >
| Yes. Two points:
| 1. The other option is /proc I guess... would that be better? I think not 
| (even though I had other optinion on this subject earlier).
Why put so much effort into this? All that is required is to refuse to
accept nonsensical parameters.

| 2. I think that it is actually good to enforce on application developers the 
| need to declare which parameters they want to use. This way they almost 
| cannot do it wrong.
| 
I don't agree: such a safety-net will only annoy good programmers who understand
what they are doing. And it will not help bad programmers much, since their problems
lie elsewhere. 

Further, the protection is not a strong one: nothing stops the user from first
declaring parameters X/Y and then supply something completely different.

| To make things clear: we both agree that the application should be able to get 
| information if the parameters it wants to use are supported by the kernel 
| it's running on, right?
| 
That is the central point. What we agree on is that that the policy should validate
the parameters that the user supplies via cmsg. We don't need the bitmask approach,
and with your suggested solution we have a mapping (.params field) between parameters
and policy IDs.

Which is sufficient to find out which parameters are acceptable for a policy.

| The place where we differ is that you would prefer to have:
| setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_POLICY_PRIO|(DCCP_SCM_PRIORITY<<8));
| 
| and I would like to have:
| setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_POLICY_PRIO);
| setsockopt(sockfd, DCCP_POLICY_PARAMS, DCCP_SCM_PRIORITY);
| 
| Is that right?
| -- 
Not quite. The first is just one way of relating policy IDs and parameters. First, as
above, I prefer your approach of using a .params field because it is simpler.    

With regard to the second point, I don't like the DCCP_POLICY_PARAMS socket option
since it does not prevent the user from using nonsensical parameters.

To summarise, what we have so far is:
 * qpolicy parameters are declared as disjoint bit values so that they can
   be or-ed together and tested with `&'/`==' operations;
 * the qpol_table gets a new (u32) field to keep the list of parameters
   that a policy accepts;
 * dccp_msghdr_parse() (net/dccp/proto.c) calls a qpolicy check routine to see
   if cmsg->cmsg_type is a parameter which is allowed by the  current qpolicy
 * if the parameter is not mentioned in the `.params' field of the qpol_table,
   dccp_msghdr_parse() returns -EINVAL.

Re: [manpages]: First stab at a udplite(7) manpage

[Michael Kerrisk]

On Mon, Jun 30, 2008 at 1:27 PM, Gerrit Renker <gerrit-VsoRXqaLlyfQzY9nttDBhA@public.gmane.org> wrote:
> |
> | The groff was fine.  I made a few light edits to the page.  I also
> | added some comments to the page with some "FIXME(gr)" pointing to
> | places where I think some work is needed.
> Thanks a lot for the review. It was particularly useful since it brought
> to light an unresolved issue: when the coverage > 65535, then unexpected
> things will happen since the internal fields are u16 and the
> setsockopt() argument is `int'.

Writing man pages tends to turn up bugs pretty often, I find.

> Will submit a bug-fix to netdev and resubmit the updated manpage when this
> issue has been resolved.

Thanks.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Tomasz Grobelny]

Gerrit Renker pisze:
> | > With the bitmask approach this constraint is expressed only once, when
> | > the policy is defined in the source file.
> | >
> | In what I propose it would also be defined once. Instead of:
> | 	[DCCPQ_POLICY_PRIO] = {
> | 		.push	= qpolicy_simple_push,
> | 		.full	= qpolicy_prio_full,
> | 		.top	= qpolicy_prio_best_skb,
> | 	},
> | we would simply have:
> | 	[DCCPQ_POLICY_PRIO] = {
> | 		.push	= qpolicy_simple_push,
> | 		.full	= qpolicy_prio_full,
> | 		.top	= qpolicy_prio_best_skb,
> | 		.params = DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT,
> | 	},
> | Doesn't seem complicated, does it?
> | 
> ... and is also simpler than the bitmask approach. Very good idea: let's use this.
> 
Ok, so now we know how to store information about parameters in kernel
structures. What remains to be discussed is how to pass that information
to userspace.

> | > With the socket approach, the constraint needs to be expressed each time
> | > the policy is used.
> | >
> | Yes. Two points:
> | 1. The other option is /proc I guess... would that be better? I think not 
> | (even though I had other optinion on this subject earlier).
> Why put so much effort into this?
Now I think that /proc is overly complicated approach.

> All that is required is to refuse to
> accept nonsensical parameters.
> 
You can refuse to accept them on sendmsg(). And IMO the application 
should be able to determine which parameters are correct earlier.

> | 2. I think that it is actually good to enforce on application developers the 
> | need to declare which parameters they want to use. This way they almost 
> | cannot do it wrong.
> | 
> I don't agree: such a safety-net will only annoy good programmers who understand
> what they are doing. And it will not help bad programmers much, since their problems
> lie elsewhere. 
> 
The history of software development shows that with newer programming 
languages you can do yourself less and less harm. Think of machine code 
-> assembler -> C -> C++ -> Java/C#. Ok, the last two languages assume 
the programmer is dumb but their success shows that people want 
fool-proof development environments (even if it restricts capabilities). 
In fact they want everything to be fool-proof (from toothbrush to car).

> Further, the protection is not a strong one: nothing stops the user from first
> declaring parameters X/Y and then supply something completely different.
> 
We could make it strong that is enforce that when a parameter was not 
declared it cannot be used.

> | To make things clear: we both agree that the application should be able to get 
> | information if the parameters it wants to use are supported by the kernel 
> | it's running on, right?
> | 
> That is the central point. What we agree on is that that the policy should validate
> the parameters that the user supplies via cmsg. 
Yes. But it's only part of the problem. We should also allow 
applications to detect which parameters are ok before calling sendmsg().

> We don't need the bitmask approach,
> and with your suggested solution we have a mapping (.params field) between parameters
> and policy IDs.
> 
> Which is sufficient to find out which parameters are acceptable for a policy.
> 
The .param field idea only shows how we store that information in 
kernel. It doesn't show how the user can retrieve that information.

> | The place where we differ is that you would prefer to have:
> | setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_POLICY_PRIO|(DCCP_SCM_PRIORITY<<8));
> | 
> | and I would like to have:
> | setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_POLICY_PRIO);
> | setsockopt(sockfd, DCCP_POLICY_PARAMS, DCCP_SCM_PRIORITY);
> | 
> | Is that right?
> | -- 
> Not quite. 
I knew we must have been talking different languages ;-)

> The first is just one way of relating policy IDs and parameters. First, as
> above, I prefer your approach of using a .params field because it is simpler.    
> 
Ok.

> To summarise, what we have so far is:
>  * qpolicy parameters are declared as disjoint bit values so that they can
>    be or-ed together and tested with `&'/`=' operations;
>  * the qpol_table gets a new (u32) field to keep the list of parameters
>    that a policy accepts;
>  * dccp_msghdr_parse() (net/dccp/proto.c) calls a qpolicy check routine to see
>    if cmsg->cmsg_type is a parameter which is allowed by the  current qpolicy
>  * if the parameter is not mentioned in the `.params' field of the qpol_table,
>    dccp_msghdr_parse() returns -EINVAL.
Yes, that's better than what we currently have (and I'll try to 
implement a patch for this).

But this still means that the application that wants to use 
DCCP_SCM_TIMEOUT can get information that it's not supported on calling 
sendmsg(). Which is IMO too late.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Gerrit Renker pisze:
> | > With the bitmask approach this constraint is expressed only once, when
> | > the policy is defined in the source file.
> | >
> | In what I propose it would also be defined once. Instead of:
> | 	[DCCPQ_POLICY_PRIO] = {
> | 		.push	= qpolicy_simple_push,
> | 		.full	= qpolicy_prio_full,
> | 		.top	= qpolicy_prio_best_skb,
> | 	},
> | we would simply have:
> | 	[DCCPQ_POLICY_PRIO] = {
> | 		.push	= qpolicy_simple_push,
> | 		.full	= qpolicy_prio_full,
> | 		.top	= qpolicy_prio_best_skb,
> | 		.params = DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT,
> | 	},
> | Doesn't seem complicated, does it?
> | 
> ... and is also simpler than the bitmask approach. Very good idea: let's use this.
> 
Ok, so now we know how to store information about parameters in kernel
structures. What remains to be discussed is how to pass that information
to userspace.

> | > With the socket approach, the constraint needs to be expressed each time
> | > the policy is used.
> | >
> | Yes. Two points:
> | 1. The other option is /proc I guess... would that be better? I think not 
> | (even though I had other optinion on this subject earlier).
> Why put so much effort into this?
Now I think that /proc is overly complicated approach.

> All that is required is to refuse to
> accept nonsensical parameters.
> 
You can refuse to accept them on sendmsg(). And IMO the application 
should be able to determine which parameters are correct earlier.

> | 2. I think that it is actually good to enforce on application developers the 
> | need to declare which parameters they want to use. This way they almost 
> | cannot do it wrong.
> | 
> I don't agree: such a safety-net will only annoy good programmers who understand
> what they are doing. And it will not help bad programmers much, since their problems
> lie elsewhere. 
> 
The history of software development shows that with newer programming 
languages you can do yourself less and less harm. Think of machine code 
-> assembler -> C -> C++ -> Java/C#. Ok, the last two languages assume 
the programmer is dumb but their success shows that people want 
fool-proof development environments (even if it restricts capabilities). 
In fact they want everything to be fool-proof (from toothbrush to car).

> Further, the protection is not a strong one: nothing stops the user from first
> declaring parameters X/Y and then supply something completely different.
> 
We could make it strong that is enforce that when a parameter was not 
declared it cannot be used.

> | To make things clear: we both agree that the application should be able to get 
> | information if the parameters it wants to use are supported by the kernel 
> | it's running on, right?
> | 
> That is the central point. What we agree on is that that the policy should validate
> the parameters that the user supplies via cmsg. 
Yes. But it's only part of the problem. We should also allow 
applications to detect which parameters are ok before calling sendmsg().

> We don't need the bitmask approach,
> and with your suggested solution we have a mapping (.params field) between parameters
> and policy IDs.
> 
> Which is sufficient to find out which parameters are acceptable for a policy.
> 
The .param field idea only shows how we store that information in 
kernel. It doesn't show how the user can retrieve that information.

> | The place where we differ is that you would prefer to have:
> | setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_POLICY_PRIO|(DCCP_SCM_PRIORITY<<8));
> | 
> | and I would like to have:
> | setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_POLICY_PRIO);
> | setsockopt(sockfd, DCCP_POLICY_PARAMS, DCCP_SCM_PRIORITY);
> | 
> | Is that right?
> | -- 
> Not quite. 
I knew we must have been talking different languages ;-)

> The first is just one way of relating policy IDs and parameters. First, as
> above, I prefer your approach of using a .params field because it is simpler.    
> 
Ok.

> To summarise, what we have so far is:
>  * qpolicy parameters are declared as disjoint bit values so that they can
>    be or-ed together and tested with `&'/`==' operations;
>  * the qpol_table gets a new (u32) field to keep the list of parameters
>    that a policy accepts;
>  * dccp_msghdr_parse() (net/dccp/proto.c) calls a qpolicy check routine to see
>    if cmsg->cmsg_type is a parameter which is allowed by the  current qpolicy
>  * if the parameter is not mentioned in the `.params' field of the qpol_table,
>    dccp_msghdr_parse() returns -EINVAL.
Yes, that's better than what we currently have (and I'll try to 
implement a patch for this).

But this still means that the application that wants to use 
DCCP_SCM_TIMEOUT can get information that it's not supported on calling 
sendmsg(). Which is IMO too late.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

[limited the lists to dccp@vger since this is DCCP-specific and not a patch]

> Ok, so now we know how to store information about parameters in kernel
> structures. What remains to be discussed is how to pass that information
> to userspace.
>
To me the less spectacular way of "just document it" still seems the best
solution. The other suggestion (below) is to divide this requirement
and, if really needed, use an API library which provides such mechanisms.

>> Further, the protection is not a strong one: nothing stops the user from 
>> first declaring parameters X/Y and then supply something completely different.
> We could make it strong that is enforce that when a parameter was not 
> declared it cannot be used.
>
Still not convinced that we need to do it in the kernel, see below.


>> | To make things clear: we both agree that the application should be able 
>> |to get information if the parameters it wants to use are supported by 
>> | the kernel it's running on, right?
>> That is the central point. What we agree on is that that the policy 
>> should validate the parameters that the user supplies via cmsg. 
> Yes. But it's only part of the problem. We should also allow applications 
> to detect which parameters are ok before calling sendmsg().
>
Please see below.

>> We don't need the bitmask approach,
>> and with your suggested solution we have a mapping (.params field) between 
>> parameters
>> and policy IDs.
>> Which is sufficient to find out which parameters are acceptable for a 
>> policy.
> The .param field idea only shows how we store that information in kernel. 
> It doesn't show how the user can retrieve that information.
>
If you want this, we could go back to the bitmask approach. That was the
original idea behind it: by encoding the parameters in a sub-bitfied of
the qpolicy ID, the set of associated parameters would be self-documenting.

But as per earlier message I don't like this idea, even if it is mine.
Protecting the user and smart mechanisms can just as well (very likely much
better) be implemented one layer above - in a "congestion API" library for
instance.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Tomasz Grobelny]

Gerrit Renker pisze:
> [limited the lists to dccp@vger since this is DCCP-specific and not a patch]
> 
>> Ok, so now we know how to store information about parameters in kernel
>> structures. What remains to be discussed is how to pass that information
>> to userspace.
>>
> To me the less spectacular way of "just document it" still seems the best
> solution. 
Documentation doesn't suffice because parameters may change from version 
to version.

> The other suggestion (below) is to divide this requirement
> and, if really needed, use an API library which provides such mechanisms.
> 
It may be that I miss something but currently I don't see how such a 
function could be implemented in a clean way. Could you please write a 
sketch of such an implementation? The function's signature could be:
	bool paramsSupported(int sockfd, int params);
and we could call it like this:
	int sockfd=socket(...);
	setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_PRIO);
	paramsSupported(sockfd, DCCP_SCM_PRIORITY); //should return true
	paramsSupported(sockfd, DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT); //should 
return false
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

Quoting Tomasz Grobelny:
> Gerrit Renker pisze:
>> [limited the lists to dccp@vger since this is DCCP-specific and not a patch]
>>
>>> Ok, so now we know how to store information about parameters in kernel
>>> structures. What remains to be discussed is how to pass that information
>>> to userspace.
>>>
>> To me the less spectacular way of "just document it" still seems the best
>> solution. 
> Documentation doesn't suffice because parameters may change from version  
> to version.
>
>> The other suggestion (below) is to divide this requirement
>> and, if really needed, use an API library which provides such mechanisms.
>>
> It may be that I miss something but currently I don't see how such a  
> function could be implemented in a clean way. Could you please write a  
> sketch of such an implementation? The function's signature could be:
> 	bool paramsSupported(int sockfd, int params);
> and we could call it like this:
> 	int sockfd=socket(...);
> 	setsockopt(sockfd, DCCP_POLICY_ID, DCCPQ_PRIO);
> 	paramsSupported(sockfd, DCCP_SCM_PRIORITY); //should return true
> 	paramsSupported(sockfd, DCCP_SCM_PRIORITY | DCCP_SCM_TIMEOUT); //should  
> return false
> -- 
We were at this point already and agreed not to change parameter <-> qdisc relationship 
between versions. 

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Thursday 03 of July 2008, Gerrit Renker napisa³:
> We were at this point already and agreed not to change parameter <-> qdisc
> relationship between versions.
No, we didn't.

I still don't get how you wish to add more parameters if there is a need to do 
so. Adding new policies is an overkill if addition of new parameters just 
extends existing functionality and does not create something completely new 
and incompatible.

I'd be grateful if you could sketch how do you wish to add new "timeout" 
parameter. Kernel implementation is not particularly important to me right 
now. I would like to know how applications are supposed to use DCCP in 4 
scenarios:
1. The application wants to use the old behaviour (that is simple policy with 
no parameters).
2. The application wants to use prio policy but needs no parameters.
3. The application wants to attach priority information to each packet.
4. The application wants to attach priority and timeout information to each 
packet. If kernel cannot process timeout then fall back to priority 
information only.
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| > We were at this point already and agreed not to change parameter <-> qdisc
| > relationship between versions.
| No, we didn't.
| 
It seems we've both lost the thread 8-)

| I still don't get how you wish to add more parameters if there is a need to do 
| so. Adding new policies is an overkill if addition of new parameters just 
| extends existing functionality and does not create something completely new 
| and incompatible.
| 
I have a sketch somewhere for adding new policies without much effort, but I can't
find the file (/tmp cleared). Will dig this out and reply to your email later.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

[-- Attachment #1: Type: text/plain, Size: 2246 bytes --]

Thank you for those scenarios -- the problem is now better to understand.

| I would like to know how applications are supposed to use DCCP in 4 scenarios:
(1) ... (3) can be handled without too many ambiguities; (4) seems to be the 
key point.

| 1. The application wants to use the old behaviour (that is simple policy with 
|    no parameters).
By setting the ID for the `simple' policy (which does not use parameters) to 0.

| 2. The application wants to use prio policy but needs no parameters.
That should not be a problem if we only check the supplied parameters.

The prio policy (any policy for that matter) needs a way of interpreting
the absence of parameters meaningfully.

| 3. The application wants to attach priority information to each packet.
This would be the default/expected case.


| 4. The application wants to attach priority and timeout information to each 
|    packet. If kernel cannot process timeout then fall back to priority 
|    information only.
I can think of at least two ways of tackling this -- maybe there are more:

  (a) Separate policies for "prio" and "prio with timeout"
      ---------------------------------------------------
      Would be resolved when trying to set "prio with timeout" policy - the
      kernel would either accept (and understand) it or return an error.

  (b) Use of optional parameters
      --------------------------
      If I understand you correctly, this is actually the way you would
      design the use of parameters, and my understanding of it is to
      that there are a few basic (well-defined) policies which could be
      combined with a number of optional additional parameters -- is that
      your idea? If this is the case then we need to step back and sort 
      out the base policies plus set of optional parameters, and find a
      way of dealing with each combination. At first sight, this seems
      more difficult and complicated than (a).

Not directly related to above questions, but rather as inspiration I
attach the sketch which I did for the definition of qpolicies. The idea
is to use a separate enum for each combination of parameters. The first
entry is initialised using the parameter bitmask, subsequent entries
have subsequent numbers.

[-- Attachment #2: main.c --]
[-- Type: text/x-csrc, Size: 1568 bytes --]

#include <stdio.h>

enum qpolicy_params {
	QP_PARAM_PRIO  = 0x1,
	QP_PARAM_TIMEO = 0x2,
	/* ... */
};

/* 4 bits = up to 16 policies sharing the same set of parameters */
#define QPOLICY_PARAM_SHIFT		4
#define QPOLICY_INITIALISER(params)	((params) << QPOLICY_PARAM_SHIFT)

enum qpolicies_that_are_without_parameters {
	DCCPQ_POLICY_SIMPLE		= 0,
	DCCPQ_POLICY_SIMPLE_DROP_ON_FULL,
};

enum qpolicies_using_only_the_prio_parameter {
	DCCPQ_POLICY_PRIO		= QPOLICY_INITIALISER(QP_PARAM_PRIO),
	DCCPQ_POLICY_REVERSE_PRIO,
	DCCPQ_POLICY_HEAP
};

enum qpolicies_using_only_the_timeo_parameter {
	DCCPQ_POLICY_TIMEO		= QPOLICY_INITIALISER(QP_PARAM_TIMEO),
};

enum qpolicies_using_both_prio_and_timeo_parameters {
	DCCPQ_POLICY_TIMED_PRIO		= QPOLICY_INITIALISER(QP_PARAM_PRIO|QP_PARAM_TIMEO),
	DCCPQ_POLICY_TIMED_REVERSE_PRIO,
	DCCPQ_POLICY_SEND_BEST_PACKET_NEXT
};

int main(void)
{
	printf("simple:                     %08x\n",   DCCPQ_POLICY_SIMPLE);
	printf("simple, dropping when full: %08x\n\n", DCCPQ_POLICY_SIMPLE_DROP_ON_FULL);

	printf("priority:                   %08x\n",   DCCPQ_POLICY_PRIO);
	printf("reverse priority:           %08x\n",   DCCPQ_POLICY_REVERSE_PRIO);
	printf("heap-based priority:        %08x\n\n", DCCPQ_POLICY_HEAP);

	printf("plain timeout:              %08x\n\n", DCCPQ_POLICY_TIMEO);

	printf("priority with timeout:      %08x\n",   DCCPQ_POLICY_TIMED_PRIO);
	printf("rev. prio. with timeout:    %08x\n",   DCCPQ_POLICY_TIMED_REVERSE_PRIO);
	printf("send-best-packet-next:      %08x\n",   DCCPQ_POLICY_SEND_BEST_PACKET_NEXT);

	return 0;
}

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Tuesday 08 of July 2008, Gerrit Renker napisa³:
> Thank you for those scenarios -- the problem is now better to understand.
>
> | I would like to know how applications are supposed to use DCCP in 4
> | scenarios:
>
> (1) ... (3) can be handled without too many ambiguities; (4) seems to be
> the key point.
>
Yes, but difference between 1 and 2 also needs some consideration.

> | 1. The application wants to use the old behaviour (that is simple policy
> | with no parameters).
>
> By setting the ID for the `simple' policy (which does not use parameters)
> to 0.
>
Which is the default, by the way.

> | 2. The application wants to use prio policy but needs no parameters.
>
> That should not be a problem if we only check the supplied parameters.
>
> The prio policy (any policy for that matter) needs a way of interpreting
> the absence of parameters meaningfully.
>
Currently prio policy should do fine. The result would be the same as if all 
packets were supplied with the same parameter. In effect 'random' packets are 
dropped.

> | 3. The application wants to attach priority information to each packet.
>
> This would be the default/expected case.
>
Yes.

> | 4. The application wants to attach priority and timeout information to
> | each packet. If kernel cannot process timeout then fall back to priority
> | information only.
>
> I can think of at least two ways of tackling this -- maybe there are more:
>
>   (a) Separate policies for "prio" and "prio with timeout"
>       ---------------------------------------------------
>       Would be resolved when trying to set "prio with timeout" policy - the
>       kernel would either accept (and understand) it or return an error.
>
So we would have "simple", "prio" and "prio with timeout" policies. The 
questions are:
1. Should we have "timeout" policy as well?
2. Should we have "prio without priority"* policy as well?

* On this example we clearly see that prio is not the best name possible. 
Maybe something like "realtime policy" would be better? Because the key 
difference to "simple" policy is the fact that send never waits (ie. the 
queue seems to be never full). Maybe there exists an even better name 
than "realtime". What do you think of changing the name?

>   (b) Use of optional parameters
>       --------------------------
>       If I understand you correctly, this is actually the way you would
>       design the use of parameters, and my understanding of it is to
>       that there are a few basic (well-defined) policies which could be
>       combined with a number of optional additional parameters -- is that
>       your idea? 
Yes. The point is: as long as you don't change the basic behaviour there is no 
need to change policy name/number. Timeout parameter would be entirely 
optional with default value of infinity. If you were to add a required 
parameter new policy would probably have to be created.

>       If this is the case then we need to step back and sort 
>       out the base policies plus set of optional parameters, and find a
>       way of dealing with each combination. At first sight, this seems
>       more difficult and complicated than (a).
>
For me it's not. Note that for each main policy you only have to think about 
two things:
1. How should it behave if all parameters are supplied.
2. If not all parameters are supplied what should be their default values. For 
priority it could be 0, for timeout it could be infinity. If you cannot think 
of a sensible default value for a parameter it is a sign that new policy 
should be created.

In effect you don't have to think about each combination of parameters 
separately.

> Not directly related to above questions, but rather as inspiration I
> attach the sketch which I did for the definition of qpolicies. The idea
> is to use a separate enum for each combination of parameters. The first
> entry is initialised using the parameter bitmask, subsequent entries
> have subsequent numbers.
> 
1. I would summarise difference in our ideas as follows:
My approach: we have an algorithm (policy) and let's think what can affect the 
behaviour of this algorithm => algorithm is first, set of parameters is 
second.
Your approach: we have a set of parameters and let's think what algorithm 
(policy) can be used to manage them => set of parameters is first, algorithm 
is second.

2. By choosing policy DCCPQ_POLICY_TIMED_REVERSE_PRIO you basically give the 
kernel two pieces of information:
  a) what set of parameters will be used (QPOLICY_INITIALISER(QP_PARAM_PRIO|
QP_PARAM_TIMEO)),
  b) how packets will be managed in a queue 
(DCCPQ_POLICY_TIMED_REVERSE_PRIO-QPOLICY_INITIALISER(QP_PARAM_PRIO|
QP_PARAM_TIMEO)).

Do we agree in these points?
-- 
Regards,
Tomasz Grobelny

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| >
| > I can think of at least two ways of tackling this -- maybe there are more:
| >
| >   (a) Separate policies for "prio" and "prio with timeout"
| >       ---------------------------------------------------
| >       Would be resolved when trying to set "prio with timeout" policy - the
| >       kernel would either accept (and understand) it or return an error.
| >
| So we would have "simple", "prio" and "prio with timeout" policies. The 
| questions are:
| 1. Should we have "timeout" policy as well?
| 2. Should we have "prio without priority"* policy as well?
| 
| * On this example we clearly see that prio is not the best name possible. 
| Maybe something like "realtime policy" would be better? Because the key 
| difference to "simple" policy is the fact that send never waits (ie. the 
| queue seems to be never full). Maybe there exists an even better name 
| than "realtime". What do you think of changing the name?
| 
I am much in support of (1) since this will be the default for many
applications which are based on a best-before time value (RTP-based
applications, video streaming for instance).

With regard to defining "salami baguette without salami", it would be best to
write short, one-sentence descriptions of the behaviour of each policy. This 
makes it easier to later add documentation (manpage) and also to find an
appropriate name. I had to look up "prio":

DCCP_SOCKOPT_QPOLICY_TXQLEN sets [...] 
the "prio" policy enforces a fixed queue length by dropping the
lowest-priority packet first.

=> So call it something like "drop_lowest_prio_first"?


| >       If this is the case then we need to step back and sort 
| >       out the base policies plus set of optional parameters, and find a
| >       way of dealing with each combination. At first sight, this seems
| >       more difficult and complicated than (a).
| >
| For me it's not. Note that for each main policy you only have to think about 
| two things:
| 1. How should it behave if all parameters are supplied.
| 2. If not all parameters are supplied what should be their default values. For 
| priority it could be 0, for timeout it could be infinity. If you cannot think 
| of a sensible default value for a parameter it is a sign that new policy 
| should be created.
| 
| In effect you don't have to think about each combination of parameters 
| separately.
| 
I am not sure I understand this. When it is used in a computer, the
parameters and the algorithm need to be well-defined.


| > Not directly related to above questions, but rather as inspiration I
| > attach the sketch which I did for the definition of qpolicies. The idea
| > is to use a separate enum for each combination of parameters. The first
| > entry is initialised using the parameter bitmask, subsequent entries
| > have subsequent numbers.
| > 
| 1. I would summarise difference in our ideas as follows:
| My approach: we have an algorithm (policy) and let's think what can affect the 
| behaviour of this algorithm => algorithm is first, set of parameters is 
| second.
| Your approach: we have a set of parameters and let's think what algorithm 
| (policy) can be used to manage them => set of parameters is first, algorithm 
| is second.
| 
| 2. By choosing policy DCCPQ_POLICY_TIMED_REVERSE_PRIO you basically give the 
| kernel two pieces of information:
|   a) what set of parameters will be used (QPOLICY_INITIALISER(QP_PARAM_PRIO|
| QP_PARAM_TIMEO)),
|   b) how packets will be managed in a queue 
| (DCCPQ_POLICY_TIMED_REVERSE_PRIO-QPOLICY_INITIALISER(QP_PARAM_PRIO|
| QP_PARAM_TIMEO)).
| 
| Do we agree in these points?
| -- 
Yes we do - we are just using different names for the same things.

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies available to userspace

[Tomasz Grobelny]

Dnia Monday 14 of July 2008, Gerrit Renker napisa³:
> | > I can think of at least two ways of tackling this -- maybe there are
> | > more:
> | >
> | >   (a) Separate policies for "prio" and "prio with timeout"
> | >       ---------------------------------------------------
> | >       Would be resolved when trying to set "prio with timeout" policy -
> | > the kernel would either accept (and understand) it or return an error.
> |
> | So we would have "simple", "prio" and "prio with timeout" policies. The
> | questions are:
> | 1. Should we have "timeout" policy as well?
> | 2. Should we have "prio without priority"* policy as well?
> |
> | * On this example we clearly see that prio is not the best name possible.
> | Maybe something like "realtime policy" would be better? Because the key
> | difference to "simple" policy is the fact that send never waits (ie. the
> | queue seems to be never full). Maybe there exists an even better name
> | than "realtime". What do you think of changing the name?
>
> I am much in support of (1) since this will be the default for many
> applications which are based on a best-before time value (RTP-based
> applications, video streaming for instance).
>
The question is not whether such a behaviour should be available to 
applications. We both agree that it should. The question is: should it be a 
separate policy? This is question about name, not about functionality.

> With regard to defining "salami baguette without salami", it would be best
> to write short, one-sentence descriptions of the behaviour of each policy.
> This makes it easier to later add documentation (manpage) and also to find
> an appropriate name. I had to look up "prio":
>
> DCCP_SOCKOPT_QPOLICY_TXQLEN sets [...]
> the "prio" policy enforces a fixed queue length by dropping the
> lowest-priority packet first.
>
> => So call it something like "drop_lowest_prio_first"?
>
But then we still have "prio" in the name. So we will 
have "drop_lowest_prio_first" without "priority". Not at all better.
Maybe just "drop", "drop_worst" (which I don't like since it has two 
words), "realtime" or "rt"?

> | >       If this is the case then we need to step back and sort
> | >       out the base policies plus set of optional parameters, and find a
> | >       way of dealing with each combination. At first sight, this seems
> | >       more difficult and complicated than (a).
> |
> | For me it's not. Note that for each main policy you only have to think
> | about two things:
> | 1. How should it behave if all parameters are supplied.
> | 2. If not all parameters are supplied what should be their default
> | values. For priority it could be 0, for timeout it could be infinity. If
> | you cannot think of a sensible default value for a parameter it is a sign
> | that new policy should be created.
> |
> | In effect you don't have to think about each combination of parameters
> | separately.
>
> I am not sure I understand this. When it is used in a computer, the
> parameters and the algorithm need to be well-defined.
>
But we only need to define only one, maximum set of parameters and not all 
permutations of these parameters. This simplifies things. At the very least 
it reduces number of needed enum values.

When you convert a string value to integer it is pretty obvious that this 
string usually contains base 10 number. But you can still define other radix 
by specifying additional parameter. By using default parameter you don't have 
to implement atoi2(), atoi8(), atoi10(), atoi16(), atoi17(), ... functions. 
Implementing just one, most complex case is enough.

Here we have the same situation: just one policy with a given behaviour is 
enough ("realtime"). If an application wants to provide priority - fine, add 
timeout - fine, add fooparam - fine, but it doesn't affect the basic 
algirithm.

> | Do we agree in these points?
> | --
>
> Yes we do - we are just using different names for the same things.
> 
Nice. So now we have to decide which names should we use in code ;-)

BTW, I'm wondering whether it would be viable to move all this qpolicy stuff 
to userspace library. Of course it is not possible with current kernel, but 
the longer we continue this discussion the more I am convinced that most of 
my code should be outside kernel... There are two practical considerations, 
though. First, it may be performance (I made no tests so I have no idea how 
big the impact might be). Second, I need to have working code for my master's 
thesis so I will not make any abrupt changes to my concept before October.
-- 
Regards,
Tomasz Grobelny

Re: [manpages]: First stab at a udplite(7) manpage

[Michael Kerrisk]

Hi Gerrit,

[...]

>> Will submit a bug-fix to netdev and resubmit the updated manpage when this
>> issue has been resolved.

Where are we with udplite.7 then?

Cheers,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [manpages]: First stab at a udplite(7) manpage

[Gerrit Renker]

Quoting Michael Kerrisk:
| Hi Gerrit,
| 
| [...]
| 
| >> Will submit a bug-fix to netdev and resubmit the updated manpage when this
| >> issue has been resolved.
| 
| Where are we with udplite.7 then?
| 
Not forgotten. Patch was submitted to netdev@vger on Monday 30th June, which 
tried to handle the illegal values consistently, i.e. return EINVAL for
 * values between 1..7 (illegal as per RFC 3828, 3.1);
 * values greater than 65535 (since IPv6 jumbograms are not supported as
   per RFC 3828, 3.5 and since the u16 value internally wraps around to 1..7).

The reply came back on Sat 5 July asking not to return EINVAL in the first case.

I haven't submitted a new patch so far since I was asking for input regarding 
these cases. Maybe someone has a good suggestion regarding this?

I will either re-post this on netdev very soon or work on a new patch.
But can't submit manpage while the API is still not clear.

Copy of email posted to netdev on Mon 7 July:
> Can I just clarify illegal checksum values, as there are two different cases:
> 
>  (a) Values between 1..7 
>      The specification marks these as illegal in RFC 3828, sec. 3.1.
>      The Linux UDP-Lite API allowed the user to get away with these illegal 
>      coverage values and documented this fact in udplite.txt. Since I am guilty
>      of having written this file, I can add that I am not aware that the same 
>      behaviour is specified in another place -- other than RFC 3828.
> 
>  (b) Values greater than 0xFFFF
>      The UDP-Lite checksum coverage field has the same u16 size as the
>      UDP Length field but, in contrast, IPv6 jumbograms are not supported
>      (RFC 3828, 3.5). This means that checksum coverage values greater than
>      65535 are undefined. 
>      Since the internal field is u16 and since the setsockopt() argument
>      is `int', there is a need to protect against this range, not only 
>      since the wrap-around can again cause values in the range 1..7.
>        
> Can you and/or other people please provide input what to do API-wise in
> the two above cases, since this information is needed for the manpage also?
> 
> These options come to mind:
> 
>   (1) Keep behaviour for (a), return EINVAL for (b).
>   (2) Keep behaviour for (a) and silently ignore values > 0xffff by
>       replacing these with "full coverage" (0) - problematic if 
>       negative values were supplied.
>   (3) Return EINVAL in both cases (as sketched by the patch).
>   (4) Other alternative?

Regards
Gerrit
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/1] [DCCP][QPOLICY]: Make information about qpolicies

[Gerrit Renker]

| > | So we would have "simple", "prio" and "prio with timeout" policies. The
| > | questions are:
| > | 1. Should we have "timeout" policy as well?
| > | 2. Should we have "prio without priority"* policy as well?
| > |
| > | * On this example we clearly see that prio is not the best name possible.
| > | Maybe something like "realtime policy" would be better? Because the key
| > | difference to "simple" policy is the fact that send never waits (ie. the
| > | queue seems to be never full). Maybe there exists an even better name
| > | than "realtime". What do you think of changing the name?
| >
| > I am much in support of (1) since this will be the default for many
| > applications which are based on a best-before time value (RTP-based
| > applications, video streaming for instance).
| >
| The question is not whether such a behaviour should be available to 
| applications. We both agree that it should. The question is: should it be a 
| separate policy? This is question about name, not about functionality.
| 
Yes - I think there should be a separate policy name for each
algorithm that uses a given set of parameters. The discussion about
multiple parameters is further below in the email; for single parameters
there is no other choice.


| > With regard to defining "salami baguette without salami", it would be best
| > to write short, one-sentence descriptions of the behaviour of each policy.
| > This makes it easier to later add documentation (manpage) and also to find
| > an appropriate name. I had to look up "prio":
| >
| > DCCP_SOCKOPT_QPOLICY_TXQLEN sets [...]
| > the "prio" policy enforces a fixed queue length by dropping the
| > lowest-priority packet first.
| >
| > => So call it something like "drop_lowest_prio_first"?
| >
| But then we still have "prio" in the name. So we will 
| have "drop_lowest_prio_first" without "priority". Not at all better.
| Maybe just "drop", "drop_worst" (which I don't like since it has two 
| words), "realtime" or "rt"?
| 
Hm - why do you not like the `prio'? After all, the way the packet is
treated is in a priority manner and the cmsg level for passing the 
associated parameter is DCCP_SCM_PRIORITY.

The algorithm is comparable to postal delivery which has only three
priorities (Express, Standard, and Economy). The obvious difference
is that postal delivery is reliable and takes longer (i.e. they use
unbounded queues), whereas the algorithm drops the packet with the
lowest priority value first.

The problem that I see with "realtime" is that it is like "multimedia",
which fits almost anything a vendor likes.

Ideally the name should briefly summarise the algorithm, it is not
so important which particular name - how about "drop_lowest_first"?



| > | >       If this is the case then we need to step back and sort
| > | >       out the base policies plus set of optional parameters, and find a
| > | >       way of dealing with each combination. At first sight, this seems
| > | >       more difficult and complicated than (a).
| > |
| > | For me it's not. Note that for each main policy you only have to think
| > | about two things:
| > | 1. How should it behave if all parameters are supplied.
| > | 2. If not all parameters are supplied what should be their default
| > | values. For priority it could be 0, for timeout it could be infinity. If
| > | you cannot think of a sensible default value for a parameter it is a sign
| > | that new policy should be created.
| > |
| > | In effect you don't have to think about each combination of parameters
| > | separately.
| >
| > I am not sure I understand this. When it is used in a computer, the
| > parameters and the algorithm need to be well-defined.
| >
| But we only need to define only one, maximum set of parameters and not all 
| permutations of these parameters. This simplifies things. At the very least 
| it reduces number of needed enum values.
| 
| When you convert a string value to integer it is pretty obvious that this 
| string usually contains base 10 number. But you can still define other radix 
| by specifying additional parameter. By using default parameter you don't have 
| to implement atoi2(), atoi8(), atoi10(), atoi16(), atoi17(), ... functions. 
| Implementing just one, most complex case is enough.
| 
Fully agree with the reasoning and this is a good idea - we use strtol() which
knows three parameters to express atoi() which only knows one parameter.

| Here we have the same situation: just one policy with a given behaviour is 
| enough ("realtime"). If an application wants to provide priority - fine, add 
| timeout - fine, add fooparam - fine, but it doesn't affect the basic 
| algorithm.
| 
I see three sets of parameters:
 1) The parameters that the algorithm knows about and which are used to
    describe the algorithm. This set is divided into two subsets
    (a) "interesting"   (which are always supplied) and
    (b) "uninteresting" (which may be absent) parameters --
    maybe in the way optional arguments are defined in C++?
 2) The parameters the algorithm does not know about -- defined as the set of
    all parameters for which dccp_qpolicy_param_ok() returns `false'.

I think what separates this from an implementation is just a bit of clerical
work, on deciding which case is the most general one and how to treat
absent parameters --- that perhaps use some default value.


| BTW, I'm wondering whether it would be viable to move all this qpolicy stuff 
| to userspace library. Of course it is not possible with current kernel, but 
| the longer we continue this discussion the more I am convinced that most of 
| my code should be outside kernel... There are two practical considerations, 
| though. First, it may be performance (I made no tests so I have no idea how 
| big the impact might be). Second, I need to have working code for my master's 
| thesis so I will not make any abrupt changes to my concept before October.
| -- 
I also thought in some instances that parts could be located in userspace.

With regard to the first consideration, what about using low-level primitives
in kernel space, from which then more complex operators/operations can be
built in user-space? Some testing/designing may be necessary, but I think
it would be great if there were a set of building blocks. As an aside, the
guy who implemented late data choice for TCP also used a user-space library.

The second consideration is no problem at all - it would be great to
have some work on this. As per earlier discussion, this is really a new
kind of API, a novel interface. Any work thus helps the progress.

Gerrit

[manpages]: Version 2 of a udplite(7) manpage

[Gerrit Renker]

[-- Attachment #1: Type: text/plain, Size: 491 bytes --]

Michael,

can you please have a look at the revised version of the udplite(7) manpage?

The main changes are:
 * the patch correcting the behaviour for large checksum coverages (> 0xffff)
   has been accepted by Dave Miller into the netdev-2.6 tree and pushed to -stable;
 * this behaviour has been documented (truncation to maximum value);
 * also attached is an rcsdiff where the responses to your Fixme's are good to see;
 * the rest is minor editorial changes.

With best regards
Gerrit

[-- Attachment #2: rcsdiff_udplite.7_since_review.diff --]
[-- Type: text/x-diff, Size: 4832 bytes --]

--- udplite.7	2008/06/27 19:09:22	1.6
+++ udplite.7	2008/07/23 15:22:34
@@ -1,7 +1,28 @@
-.\" FIXME(gr) we need a license for this page.
-.\" The one I tend to favor is shown in the capabilities.7 page,
-.\" but others are also used in man-pages (e.g., GPL, BSD).
-.TH UDPLITE  7 2008-06-23 "Linux" "Linux Programmer's Manual"
+.\" Copyright (c) 2008 by Gerrit Renker <gerrit-VsoRXqaLlyfQzY9nttDBhA@public.gmane.org>
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\"
+.\" $Id: udplite.7,v 1.12 2008/07/23 15:22:22 gerrit Exp gerrit $
+.\"
+.TH UDPLITE  7 2008-07-23 "Linux" "Linux Programmer's Manual"
 .SH NAME
 udplite \- Lightweight User Datagram Protocol
 .SH SYNOPSIS
@@ -18,15 +39,9 @@
 
 UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length
 checksums.
-This has advantages for some types of multimedia transport,
-since it makes it possible to reuse partly damaged frames
-(with few bit errors).
-.\" FIXME(gr) is "reuse" the right word in the previous sentence?
-.\" Reading the RFC suggests to me that a better wording might be:
-.\"
-.\" This has advantages for some types of multimedia transport that
-.\" may be able to make use of slightly damaged datagrams,
-.\" rather than having them discarded by lower layer protocols.
+This has advantages for some types of multimedia transport that
+may be able to make use of slightly damaged datagrams,
+rather than having them discarded by lower-layer protocols.
 
 The variable-length checksum coverage is set via a
 .BR setsockopt (2)
@@ -68,16 +83,15 @@
 .B int
 as argument, with a checksum coverage value in the range 0..2^16-1.
 
-A value of 0 means that the entire datagram is always covered,
-values from 1-7 are illegal (RFC\ 3828, 3.1) and are rounded up to
+A value of 0 means that the entire datagram is always covered.
+Values from 1-7 are illegal (RFC\ 3828, 3.1) and are rounded up to
 the minimum coverage of 8.
 
 With regard to IPv6 jumbograms (RFC\ 2675), the UDP-Litev6 checksum
 coverage is limited to the first 2^16-1 octets, as per RFC\ 3828, 3.5.
-Higher values are therefore not supported.
-.\" FIXME(gr) If higher values are specified, what happens?
-.\" If they are silently ignored, probably we should explicitly
-.\" say so here.
+Higher values are therefore silently truncated to 2^16-1.
+If in doubt, the current coverage value can always be queried using
+.BR getsockopt (2).
 .TP
 .BR UDPLITE_RECV_CSCOV
 This is the receiver-side analogue and uses uses the same argument format
@@ -89,6 +103,11 @@
 instructs the kernel to drop all packets which have a coverage
 .I less
 than the specified coverage value.
+
+When the value of
+.B UDPLITE_RECV_CSCOV
+exceeds the actual packet coverage, incoming packets are silently dropped,
+but may generate a warning message in the system log.
 .\" FIXME: SO_NO_CHECK exists and is supported by UDPv4, but is
 .\" commented out in socket(7), hence also here ???
 .\".PP
@@ -102,10 +121,6 @@
 .BR udp (7)
 may be returned.
 UDP-Lite does not add further errors.
-When the value of
-.B UDPLITE_RECV_CSCOV
-exceeds the actual coverage, incoming packets are silently dropped,
-but may generate a warning message in the system log.
 .SH BUGS
 .\" FIXME: remove this section once glibc supports UDP-Lite
 Where glibc support is missing, the following definitions are needed:
@@ -120,11 +135,10 @@
 .in
 .SH FILES
 .I /proc/net/snmp
+\- basic UDP-Litev4 statistics counters.
 .br
-.IR /proc/net/snmp6
-.\" FIXME(gr)
-.\" Could you add some discussion of the UDPLITE-specific
-.\" info in these files?
+.I /proc/net/snmp6
+\- basic UDP-Litev6 statistics counters.
 .SH VERSIONS
 UDP-Litev4/v6 first appeared in Linux 2.6.20.
 .SH "SEE ALSO"
@@ -136,4 +150,3 @@
 RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite)
 .br
 .I Documentation/networking/udplite.txt
-

[-- Attachment #3: udplite.7 --]
[-- Type: text/plain, Size: 5075 bytes --]

.\" Copyright (c) 2008 by Gerrit Renker <gerrit-VsoRXqaLlyfQzY9nttDBhA@public.gmane.org>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" $Id: udplite.7,v 1.12 2008/07/23 15:22:22 gerrit Exp gerrit $
.\"
.TH UDPLITE  7 2008-07-23 "Linux" "Linux Programmer's Manual"
.SH NAME
udplite \- Lightweight User Datagram Protocol
.SH SYNOPSIS
.B #include <sys/socket.h>
.br
.\" FIXME: see #defines under `BUGS',
.\"        when glibc supports this, add
.\"        #include <netinet/udplite.h>
.sp
.B s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
.SH DESCRIPTION
This is an implementation of the Lightweight User Datagram Protocol
(UDP-Lite), as described in RFC\ 3828.

UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length
checksums.
This has advantages for some types of multimedia transport that
may be able to make use of slightly damaged datagrams,
rather than having them discarded by lower-layer protocols.

The variable-length checksum coverage is set via a
.BR setsockopt (2)
option.
If this option is not set, the only difference to UDP is
in using a different IP protocol identifier (IANA number 136).

The UDP-Lite implementation is a full extension of
.BR udp (7),
i.e., it shares the same API and API behaviour, and in addition
offers two socket options to control the checksum coverage.
.SS "Address Format"
UDP-Litev4 uses the
.I sockaddr_in
address format described in
.BR ip (7).
UDP-Litev6 uses the
.I sockaddr_in6
address format described in
.BR ipv6 (7).
.SS "Socket Options"
To set or get a UDP-Lite socket option, call
.BR getsockopt (2)
to read or
.BR setsockopt (2)
to write the option with the option level argument set to
.BR IPPROTO_UDPLITE .
In addition, all
.B IPPROTO_UDP
socket options are valid on a UDP-Lite socket.
See
.BR udp (7)
for more information.

The following two options are specific to UDP-Lite.
.TP
.BR UDPLITE_SEND_CSCOV
This option sets the sender checksum coverage and takes an
.B int
as argument, with a checksum coverage value in the range 0..2^16-1.

A value of 0 means that the entire datagram is always covered.
Values from 1-7 are illegal (RFC\ 3828, 3.1) and are rounded up to
the minimum coverage of 8.

With regard to IPv6 jumbograms (RFC\ 2675), the UDP-Litev6 checksum
coverage is limited to the first 2^16-1 octets, as per RFC\ 3828, 3.5.
Higher values are therefore silently truncated to 2^16-1.
If in doubt, the current coverage value can always be queried using
.BR getsockopt (2).
.TP
.BR UDPLITE_RECV_CSCOV
This is the receiver-side analogue and uses uses the same argument format
and value range as
.BR UDPLITE_SEND_CSCOV .
This option is not required to enable traffic with partial checksum
coverage.
Its function is that of a traffic filter: when enabled, it
instructs the kernel to drop all packets which have a coverage
.I less
than the specified coverage value.

When the value of
.B UDPLITE_RECV_CSCOV
exceeds the actual packet coverage, incoming packets are silently dropped,
but may generate a warning message in the system log.
.\" FIXME: SO_NO_CHECK exists and is supported by UDPv4, but is
.\" commented out in socket(7), hence also here ???
.\".PP
.\"Since UDP-Lite mandates checksums, checksumming can not be disabled
.\"via the
.\".B SO_NO_CHECK
.\"option from
.\".BR socket (7).
.SH ERRORS
All errors documented for
.BR udp (7)
may be returned.
UDP-Lite does not add further errors.
.SH BUGS
.\" FIXME: remove this section once glibc supports UDP-Lite
Where glibc support is missing, the following definitions are needed:
.in +4n
.nf

#define IPPROTO_UDPLITE     136
.\" The following two are defined in the kernel in linux/net/udplite.h
#define UDPLITE_SEND_CSCOV  10
#define UDPLITE_RECV_CSCOV  11
.fi
.in
.SH FILES
.I /proc/net/snmp
\- basic UDP-Litev4 statistics counters.
.br
.I /proc/net/snmp6
\- basic UDP-Litev6 statistics counters.
.SH VERSIONS
UDP-Litev4/v6 first appeared in Linux 2.6.20.
.SH "SEE ALSO"
.BR udp (7),
.BR ip (7),
.BR ipv6 (7),
.BR socket (7)

RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite)
.br
.I Documentation/networking/udplite.txt

Re: [manpages]: Version 2 of a udplite(7) manpage

[Michael Kerrisk]

Gerrit,

Gerrit Renker wrote:
> Michael,
> 
> can you please have a look at the revised version of the udplite(7) manpage?
> 
> The main changes are:
>  * the patch correcting the behaviour for large checksum coverages (> 0xffff)
>    has been accepted by Dave Miller into the netdev-2.6 tree and pushed to -stable;
>  * this behaviour has been documented (truncation to maximum value);

Okay.

>  * also attached is an rcsdiff where the responses to your Fixme's are good to see;

Thanks for that -- much easier to see what you did in response to my comments.

>  * the rest is minor editorial changes.

Yep.

Thanks for this revision.  I made one or two small edits.  The most notable
is that I changed PF_INET to AF_INET in the SYNOPSIS.  (As fas as POSIX.1
is concerned, the PF_* constants are obsolete, in favour of the AF_*
constants with the same value.)  I think we're good to go otherwise, and
I'll include this page in man-pages-3.07, unless you think some further work
still needs to be done.

Cheers,

Michael

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [manpages]: Version 2 of a udplite(7) manpage

[Michael Kerrisk]

[Restored linux-man to CC]

Hi Gerrit,

On Fri, Aug 8, 2008 at 1:05 PM,  <gerrit-VsoRXqaLlyfQzY9nttDBhA@public.gmane.org> wrote:
> Hi Michael,
>
>> I made one or two small edits.  The most notable
>> is that I changed PF_INET to AF_INET in the SYNOPSIS.  (As fas as POSIX.1
>> is concerned, the PF_* constants are obsolete, in favour of the AF_*
>> constants with the same value.)  I think we're good to go otherwise, and
>> I'll include this page in man-pages-3.07, unless you think some further
>> work still needs to be done.
>>
> I can't think of further work items at the moment.

Good.  udplite.7 will be in man-pages-3.07.  Thanks for writing it!

> Thank you for the AF/PF
> clarification, something which continues to confuse me (and likely others).
>
> Since I copied the example from udp(7), would it make sense to extend this
> update to that manpage as well? A quick check in tcp(7) and ip(7), raw(7),
> socket(7) showed that somehow the AF/PF ambiguity appears in other places
> as well (netlink(7) is likely not Posix).

Yes, it's been one of those nagging little tasks I've been meaning to
do for a while.  (My reluctance has been in part about whether I
should "erase history" -- the pseudo-distinction between AF_ and PF_
is longstanding, but has also been meaningless since the beginning.)
So, you're comment finally prompted me to do it.  In man-pages-3.07,
everything is now AF_*.

Thanks

Michael




-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html