xref: /f-stack/tools/README.md (revision df6ad731) 
1# Introduction
2
3Directory `compat` implements an ipc library using dpdk `rte_ring` and ports some source files compatible with FreeBSD and Linux.
4
5All other directories are useful tools ported from FreeBSD.
6Since F-Stack is multi-process architecture and every process has an independent stack, so we must communicate with every F-Stack process.
7Each tool add an option `-p`(Which F-Stack process to communicate with, default 0), except that, it is same with the original FreeBSD.
8
9Note that these tools must be executed serially.
10
11# sysctl
12Usage:
13```
14sysctl -p <f-stack proc_id> [-bdehiNnoqTtWx] [ -B <bufsize> ] [-f filename] name[=value] ...
15sysctl -p <f-stack proc_id> [-bdehNnoqTtWx] [ -B <bufsize> ] -a
16```
17For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?sysctl).
18
19# ifconfig
20Usage:
21```
22ifconfig -p <f-stack proc_id> [-f type:format] %sinterface address_family
23        [address [dest_address]] [parameters]
24    ifconfig -p <f-stack proc_id> interface create
25    ifconfig -p <f-stack proc_id> -a %s[-d] [-m] [-u] [-v] [address_family]
26    ifconfig -p <f-stack proc_id> -l [-d] [-u] [address_family]
27    ifconfig -p <f-stack proc_id> %s[-d] [-m] [-u] [-v]
28```
29Unsupported interfaces or parameters:
30```
31inet6
32MAC(Mandatory Access Control)
33media
34SFP/SFP+
35IEEE80211 Wireless
36pfsync
37LAGG LACP
38jail
39```
40For more details, see [Manual page](https://www.freebsd.org/cgi/man.cgi?ifconfig).
41
42# how to implement a custom tool for communicating with F-Stack process
43
44Add a new FF_MSG_TYPE in ff_msg.h:
45```
46enum FF_MSG_TYPE {
47    FF_UNKNOWN = 0,
48    FF_SYSCTL,
49    FF_HELLOWORLD,
50};
51```
52
53Define a structure used to communicate:
54```
55struct ff_helloworld_args {
56    void *request;
57    size_t req_len;
58    void *reply;
59    size_t rep_len;
60};
61```
62Note that, when using struct ff_helloworld_args, pointers in this structure must point to the addresses range from ff_msg.buf_addr and ff_msg.buf_addr+ff_msg.buf_len, ff_msg.buf_len is (10240 - sizeof(struct ff_msg)).
63
64And add it to ff_msg:
65```
66struct ff_msg {
67    ...
68    union {
69        struct ff_sysctl_args sysctl;
70        struct ff_helloworld_args helloworld;
71    };
72};
73```
74
75Modify ff_dpdk_if.c, add a handle function:
76```
77static inline void
78handle_helloworld_msg(struct ff_msg *msg, uint16_t proc_id)
79{
80    printf("helloworld msg recved.\n");
81    msg->result = 0;
82    rte_ring_enqueue(msg_ring[proc_id].ring[1], msg);
83}
84
85static inline void
86handle_msg(struct ff_msg *msg, uint16_t proc_id)
87{
88    switch (msg->msg_type) {
89        case FF_SYSCTL:
90            handle_sysctl_msg(msg, proc_id);
91            break;
92        case FF_HELLOWORLD:
93            handle_helloworld_msg(msg, proc_id);
94        default:
95            handle_default_msg(msg, proc_id);
96            break;
97    }
98}
99```
100
101Create helloworld.c:
102
103```
104int main()
105{
106    struct ff_msg *msg = ff_ipc_msg_alloc();
107
108    char *buf = msg->buf_addr;
109
110    msg->helloworld.request = buf;
111    memcpy(msg->helloworld.request, "hello", 5);
112    msg->helloworld.req_len = 5;
113    buf += 5;
114
115    msg->helloworld.reply = buf;
116    msg->helloworld.rep_len = 10;
117
118    ff_ipc_send(msg, 0);
119
120    struct ff_msg *retmsg;
121    ff_ipc_recv(retmsg, 0);
122    assert(remsg==msg);
123
124    ff_ipc_msg_free(msg);
125}
126
127```
128
129The Makefile may like this:
130```
131TOPDIR?=${CURDIR}/../..
132
133PROG=helloworld
134
135include ${TOPDIR}/tools/prog.mk
136```
137