Root/package/swconfig/src/swlib.h

1/*
2 * swlib.h: Switch configuration API (user space part)
3 *
4 * Copyright (C) 2008-2009 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
16Usage 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
55Usage 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
74Usage 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
98enum swlib_attr_group {
99    SWLIB_ATTR_GROUP_GLOBAL,
100    SWLIB_ATTR_GROUP_VLAN,
101    SWLIB_ATTR_GROUP_PORT,
102};
103
104enum swlib_port_flags {
105    SWLIB_PORT_FLAG_TAGGED = (1 << 0),
106};
107
108
109struct switch_dev;
110struct switch_attr;
111struct switch_port;
112struct switch_val;
113struct uci_package;
114
115struct switch_dev {
116    int id;
117    char dev_name[IFNAMSIZ];
118    const char *name;
119    const char *alias;
120    int ports;
121    int vlans;
122    int cpu_port;
123    struct switch_attr *ops;
124    struct switch_attr *port_ops;
125    struct switch_attr *vlan_ops;
126    struct switch_dev *next;
127    void *priv;
128};
129
130struct switch_val {
131    struct switch_attr *attr;
132    int len;
133    int err;
134    int port_vlan;
135    union {
136        const char *s;
137        int i;
138        struct switch_port *ports;
139    } value;
140};
141
142struct switch_attr {
143    struct switch_dev *dev;
144    int atype;
145    int id;
146    int type;
147    const char *name;
148    const char *description;
149    struct switch_attr *next;
150};
151
152struct switch_port {
153    unsigned int id;
154    unsigned int flags;
155};
156
157/**
158 * swlib_connect: connect to the switch through netlink
159 * @name: name of the ethernet interface,
160 *
161 * if name is NULL, it connect and builds a chain of all switches
162 */
163struct switch_dev *swlib_connect(const char *name);
164
165/**
166 * swlib_free: free all dynamically allocated data for the switch connection
167 * @dev: switch device struct
168 *
169 * all members of a switch device chain (generated by swlib_connect(NULL))
170 * must be freed individually
171 */
172void swlib_free(struct switch_dev *dev);
173
174/**
175 * swlib_free_all: run swlib_free on all devices in the chain
176 * @dev: switch device struct
177 */
178void swlib_free_all(struct switch_dev *dev);
179
180/**
181 * swlib_scan: probe the switch driver for available commands/attributes
182 * @dev: switch device struct
183 */
184int swlib_scan(struct switch_dev *dev);
185
186/**
187 * swlib_lookup_attr: look up a switch attribute
188 * @dev: switch device struct
189 * @type: global, port or vlan
190 * @name: name of the attribute
191 */
192struct switch_attr *swlib_lookup_attr(struct switch_dev *dev,
193        enum swlib_attr_group atype, const char *name);
194
195/**
196 * swlib_set_attr: set the value for an attribute
197 * @dev: switch device struct
198 * @attr: switch attribute struct
199 * @val: attribute value pointer
200 * returns 0 on success
201 */
202int swlib_set_attr(struct switch_dev *dev, struct switch_attr *attr,
203        struct switch_val *val);
204
205/**
206 * swlib_set_attr_string: set the value for an attribute with type conversion
207 * @dev: switch device struct
208 * @attr: switch attribute struct
209 * @port_vlan: port or vlan (if applicable)
210 * @str: string value
211 * returns 0 on success
212 */
213int swlib_set_attr_string(struct switch_dev *dev, struct switch_attr *attr,
214        int port_vlan, const char *str);
215
216/**
217 * swlib_get_attr: get the value for an attribute
218 * @dev: switch device struct
219 * @attr: switch attribute struct
220 * @val: attribute value pointer
221 * returns 0 on success
222 * for string attributes, the result string must be freed by the caller
223 */
224int swlib_get_attr(struct switch_dev *dev, struct switch_attr *attr,
225        struct switch_val *val);
226
227/**
228 * swlib_apply_from_uci: set up the switch from a uci configuration
229 * @dev: switch device struct
230 * @p: uci package which contains the desired global config
231 */
232int swlib_apply_from_uci(struct switch_dev *dev, struct uci_package *p);
233
234#endif
235

Archive Download this file

Branches:
backfire
history
master
release_2010-11-17
release_2010-12-14
release_2011-02-23
release_2011-05-28
release_2011-08-27
release_2011-11-13
release_2012-03-18
release_2012-04-09
release_2012-10-11
uclibc_nptl



interactive