1 Introduction
2 ============
3
4 This is a collection of L4Re packages for providing and using filesystems and
5 related components.
6
7 This directory (departure) should be installed within the pkg directory in the
8 L4Re distribution.
9
10 Prerequisites
11 =============
12
13 This software requires some other software to be useful:
14
15 * The Fiasco.OC microkernel and L4Re distribution
16 * The idl4re distribution
17
18 Obtaining and Building idl4re
19 =============================
20
21 The idl4re distribution provides a tool called idl that generates source files
22 from interface descriptions. It can be obtained as follows:
23
24 hg clone https://hg.boddie.org.uk/L4Re/idl4re
25
26 The software can be built as follows:
27
28 cd idl4re
29 make
30
31 When building the Departure software within the L4Re build system, the idl4re
32 directory will need to be present in the appropriate location, this being
33 inside the l4 directory. See below for more details.
34
35 Obtaining and Building Fiasco.OC and L4Re
36 =========================================
37
38 Although the build processes for Fiasco.OC and L4Re are generally documented,
39 the concise instructions for building the software have not been preserved in
40 the L4Re distribution, requiring the perusal of online resources. For example:
41
42 https://github.com/kernkonzept/manifest/wiki/BUILDING
43
44 Some reminders are provided below to save the reader the bother of looking up
45 or searching for this information, particularly if it does not continue to
46 reside in the above location.
47
48 Obtaining and Building the ham Tool
49 -----------------------------------
50
51 First of all, the ham tool has to be obtained. This can be done as follows:
52
53 git clone https://github.com/kernkonzept/ham.git
54
55 It can be built as follows:
56
57 cd ham
58 make
59
60 Returning to the parent directory, the Fiasco.OC and L4Re distributions can be
61 obtained as follows:
62
63 ham/ham init -u https://github.com/kernkonzept/manifest.git
64 ham/ham sync
65
66 (Referencing ham within its repository avoids any need to put the program on
67 the PATH, which is largely unnecessary since we will only be using it in this
68 particular location and for the specific purpose of downloading the remaining
69 software of interest.)
70
71 Building Fiasco.OC
72 ------------------
73
74 Here is a quick summary of the build process for Fiasco.OC starting at the
75 parent directory of the Fiasco.OC and L4Re distributions:
76
77 cd fiasco
78 make BUILDDIR=mybuild
79 cd mybuild
80 make config
81 make
82
83 The final make command can employ flags such as "-j8" or even "-j" without any
84 parameter to parallelise the build.
85
86 At this point, this directory (departure) can be copied into the L4Re
87 distribution within the pkg directory. Also, the idl4re distribution should be
88 made available within the l4 directory itself.
89
90 Possible L4Re Fix
91 -----------------
92
93 It appears that the following file may need a fix or workaround for a problem
94 where IPC communications employ a bad protocol type:
95
96 pkg/l4re-core/l4sys/include/cxx/ipc_iface
97
98 Prior to this line...
99
100 // handle in-data part of the arguments
101 int send_bytes =
102 Args::template write_op<Do_in_data>(mrs->mr, 0, Mr_bytes,
103 Opt::Opcode, a...);
104
105 ...it appears necessary to introduce the following statement:
106
107 mrs->mr[0] = 0;
108
109 Building L4Re
110 -------------
111
112 Here is a quick summary of the build process for L4Re, also starting at the
113 parent directory of the Fiasco.OC and L4Re distributions:
114
115 cd l4
116 make B=mybuild
117 make O=mybuild config
118 make O=mybuild
119
120 Again, the final make command can employ parallelisation flags. For example:
121
122 make -j8 O=mybuild
123
124 Along with the usual L4Re software, this will also build the software provided
125 by this distribution if it has been copied into the pkg/departure location
126 within the l4 directory.
127
128 Defining the L4Re Configuration
129 ===============================
130
131 An example configuration file is provided as conf/Makeconf.boot within this
132 distribution. Where no such existing file has been deployed, this example file
133 can be copied into a suitable location from within the l4 directory as
134 follows:
135
136 cp pkg/departure/conf/Makeconf.boot conf/Makeconf.boot
137
138 Otherwise, with an existing conf/Makeconf.boot file, to make the test programs
139 available to L4Re, add the following line to such a file:
140
141 MODULE_SEARCH_PATH += $(L4DIR_ABS)/pkg/departure/conf
142
143 It may also be necessary to add the following line as well:
144
145 BOOTSTRAP_SEARCH_PATH += $(L4DIR_ABS)/pkg/departure/conf
146
147 This removes any need to copy program configuration files and associated
148 resources to the L4Re distribution itself.
149
150 Defining the Module Lists
151 =========================
152
153 The program module lists in the conf subdirectory can either be appended to
154 the L4Re conf/modules.list file, or a specific .list file can be copied to the
155 conf/modules.list location (potentially after taking a backup copy of the
156 original file). For example, from within the l4 directory:
157
158 cp conf/modules.list conf/modules.list.orig
159 cp pkg/departure/conf/dstest_test.list conf/modules.list
160
161 Running Programs from this Distribution
162 =======================================
163
164 With configuration measures in place, a program can be run in QEMU as follows:
165
166 make O=mybuild qemu E=dstest_test
167
168 The particular program used above is a short concurrency test.