add new switch configuration api
[openwrt/svn-archive/archive.git] / package / swconfig / src / swlib.h
1 /*
2 * swlib.h: Switch configuration API (user space part)
3 *
4 * Copyright (C) 2008 Felix Fietkau <nbd@openwrt.org>
5 *
6 * This program is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public License
8 * version 2.1 as published by the Free Software Foundation.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15
16 Usage of the library functions:
17
18 The main datastructure for a switch is the struct switch_device
19 To get started, you first need to use switch_connect() to probe
20 for switches and allocate an instance of this struct.
21
22 There are two possible usage modes:
23 dev = switch_connect("eth0");
24 - this call will look for a switch registered for the linux device
25 "eth0" and only allocate a switch_device for this particular switch.
26
27 dev = switch_connect(NULL)
28 - this will return one switch_device struct for each available
29 switch. The switch_device structs are chained with by ->next pointer
30
31 Then to query a switch for all available attributes, use:
32 swlib_scan(dev);
33
34 All allocated datastructures for the switch_device struct can be freed with
35 swlib_free(dev);
36 or
37 swlib_free_all(dev);
38
39 The latter traverses a whole chain of switch_device structs and frees them all
40
41 Switch attributes (struct switch_attr) are divided into three groups:
42 dev->ops:
43 - global settings
44 dev->port_ops:
45 - per-port settings
46 dev->vlan_ops:
47 - per-vlan settings
48
49 switch_lookup_attr() is a small helper function to locate attributes
50 by name.
51
52 switch_set_attr() and switch_get_attr() can alter or request the values
53 of attributes.
54
55 Usage of the switch_attr struct:
56
57 ->atype: attribute group, one of:
58 - SWLIB_ATTR_GROUP_GLOBAL
59 - SWLIB_ATTR_GROUP_VLAN
60 - SWLIB_ATTR_GROUP_PORT
61
62 ->id: identifier for the attribute
63
64 ->type: data type, one of:
65 - SWITCH_TYPE_INT
66 - SWITCH_TYPE_STRING
67 - SWITCH_TYPE_PORT
68
69 ->name: short name of the attribute
70 ->description: longer description
71 ->next: pointer to the next attribute of the current group
72
73
74 Usage of the switch_val struct:
75
76 When setting attributes, following members of the struct switch_val need
77 to be set up:
78
79 ->len (for attr->type == SWITCH_TYPE_PORT)
80 ->port_vlan:
81 - port number (for attr->atype == SWLIB_ATTR_GROUP_PORT), or:
82 - vlan number (for attr->atype == SWLIB_ATTR_GROUP_VLAN)
83 ->value.i (for attr->type == SWITCH_TYPE_INT)
84 ->value.s (for attr->type == SWITCH_TYPE_STRING)
85 - owned by the caller, not stored in the library internally
86 ->value.ports (for attr->type == SWITCH_TYPE_PORT)
87 - must point to an array of at lest val->len * sizeof(struct switch_port)
88
89 When getting string attributes, val->value.s must be freed by the caller
90 When getting port list attributes, an internal static buffer is used,
91 which changes from call to call.
92
93 */
94
95 #ifndef __SWLIB_H
96 #define __SWLIB_H
97
98 enum swlib_attr_group {
99 SWLIB_ATTR_GROUP_GLOBAL,
100 SWLIB_ATTR_GROUP_VLAN,
101 SWLIB_ATTR_GROUP_PORT,
102 };
103
104 enum swlib_port_flags {
105 SWLIB_PORT_FLAG_TAGGED = (1 << 0),
106 };
107
108
109 struct switch_dev;
110 struct switch_attr;
111 struct switch_port;
112 struct switch_val;
113
114 struct switch_dev {
115 int id;
116 const char *name;
117 const char *dev_name;
118 int ports;
119 int vlans;
120 struct switch_attr *ops;
121 struct switch_attr *port_ops;
122 struct switch_attr *vlan_ops;
123 struct switch_dev *next;
124 void *priv;
125 };
126
127 struct switch_val {
128 struct switch_attr *attr;
129 int len;
130 int err;
131 int port_vlan;
132 union {
133 const char *s;
134 int i;
135 struct switch_port *ports;
136 } value;
137 };
138
139 struct switch_attr {
140 struct switch_dev *dev;
141 int atype;
142 int id;
143 int type;
144 const char *name;
145 const char *description;
146 struct switch_attr *next;
147 };
148
149 struct switch_port {
150 unsigned int id;
151 unsigned int flags;
152 };
153
154 /**
155 * swlib_connect: connect to the switch through netlink
156 * @name: name of the ethernet interface,
157 *
158 * if name is NULL, it connect and builds a chain of all switches
159 */
160 struct switch_dev *swlib_connect(const char *name);
161
162 /**
163 * swlib_free: free all dynamically allocated data for the switch connection
164 * @dev: switch device struct
165 *
166 * all members of a switch device chain (generated by swlib_connect(NULL))
167 * must be freed individually
168 */
169 void swlib_free(struct switch_dev *dev);
170
171 /**
172 * swlib_free_all: run swlib_free on all devices in the chain
173 * @dev: switch device struct
174 */
175 void swlib_free_all(struct switch_dev *dev);
176
177 /**
178 * swlib_scan: probe the switch driver for available commands/attributes
179 * @dev: switch device struct
180 */
181 int swlib_scan(struct switch_dev *dev);
182
183 /**
184 * swlib_lookup_attr: look up a switch attribute
185 * @dev: switch device struct
186 * @type: global, port or vlan
187 * @name: name of the attribute
188 */
189 struct switch_attr *swlib_lookup_attr(struct switch_dev *dev,
190 enum swlib_attr_group atype, const char *name);
191
192 /**
193 * swlib_set_attr: set the value for an attribute
194 * @dev: switch device struct
195 * @attr: switch attribute struct
196 * @val: attribute value pointer
197 * returns 0 on success
198 */
199 int swlib_set_attr(struct switch_dev *dev, struct switch_attr *attr,
200 struct switch_val *val);
201
202 /**
203 * swlib_get_attr: get the value for an attribute
204 * @dev: switch device struct
205 * @attr: switch attribute struct
206 * @val: attribute value pointer
207 * returns 0 on success
208 * for string attributes, the result string must be freed by the caller
209 */
210 int swlib_get_attr(struct switch_dev *dev, struct switch_attr *attr,
211 struct switch_val *val);
212
213 #endif