Skip to content

Commit f2951f2

Browse files
NIBRSYK16NIBRSYK16
authored
docs: added detailed user documents (#275)
* added content of README.md and create ./doc directory with two helping documents
1 parent 5882539 commit f2951f2

File tree

3 files changed

+232
-5
lines changed

3 files changed

+232
-5
lines changed

‎README.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -31,16 +31,14 @@ AlloyStack/
3131
│ └── *.json # workflow specification files
3232
├── fs_images/
3333
│ └── *.img # file system images
34+
├── doc/
35+
│ └── ... # detailed documents
3436
```
3537

3638

3739
To run a new test application on AlloyStack, user need to develop functions in the `user/` directory. Then, edit the workflow specification files in the `isol_config/` directory to declare how functions compose the workflow, specify dependencies on LibOS modules, and define input parameters for functions. If the workflow involves reading datasets from files, the datasets must also be added to the file system image. Please use the following command to extract the provided image archive, which contains the source code for the Python benchmarks.
3840

39-
```bash
40-
AlloyStack$ just init
41-
```
42-
43-
Additionally, the repository of AlloyStack is integrated with GitHub Actions. Therefore, tools such as [act](https://github.com/nektos/act) can be used locally to quickly run some basic test cases via Docker.
41+
For detailed documentation, please refer to [AlloyStack User Guide](./doc/).
4442

4543
## Evaluation
4644
### Cold start latency

‎doc/content_included_in_justfile.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Justfile Script Tools Reference
2+
3+
## Utility Tools
4+
5+
### Data Management
6+
```
7+
# Generate test data
8+
AlloyStack$ just gen_data
9+
10+
# Initialize environment
11+
AlloyStack$ just init
12+
```
13+
14+
## Build Commands
15+
16+
### System Services
17+
```
18+
# Build all LibOS modules
19+
AlloyStack$ just all_libos
20+
21+
# Build specific LibOS module
22+
AlloyStack$ just libos <module_name> # e.g., just libos stdio
23+
```
24+
25+
### User Functions
26+
```
27+
# Build Rust user function
28+
AlloyStack$ just rust_func <function_name> # e.g., just rust_func mapper
29+
30+
# Build WASM user function
31+
AlloyStack$ just wasm_func <function_name> # e.g., just wasm_func wasmtime_mapper
32+
```
33+
34+
### Workflow-Specific Builds
35+
```
36+
# Build MapReduce components
37+
AlloyStack$ just map_reduce
38+
39+
# Build Parallel Sort components
40+
AlloyStack$ just parallel_sort
41+
42+
# Build Long Chain components
43+
AlloyStack$ just long_chain
44+
45+
# Build Simple File components
46+
AlloyStack$ just simple_file
47+
```
48+
49+
## Test Execution Tools
50+
### Performance Tests
51+
```
52+
# Run cold start latency tests
53+
AlloyStack$ just cold_start_latency
54+
55+
# Run data transfer latency tests
56+
AlloyStack$ just data_transfer_latency
57+
58+
# Run end-to-end latency tests
59+
AlloyStack$ just end_to_end_latency
60+
61+
# Run breakdown analysis
62+
AlloyStack$ just breakdown
63+
64+
# Run P99 latency tests
65+
AlloyStack$ just p99
66+
67+
# Measure resource consumption
68+
AlloyStack$ just resource_consume
69+
```
70+
71+
### WASM Application Tests
72+
73+
```
74+
# Test C WASM applications
75+
AlloyStack$ just c_end_to_end_latency
76+
77+
# Test Python WASM applications
78+
AlloyStack$ just py_end_to_end_latency
79+
```
80+
81+
## Workflow-Specific Scripts
82+
83+
### C Applications
84+
```
85+
# Build and test C wordcount
86+
AlloyStack$ just c_wordcount
87+
88+
# Build and test C parallel sort
89+
AlloyStack$ just c_parallel_sort
90+
91+
# Build and test C long chain
92+
AlloyStack$ just c_long_chain
93+
```
94+
95+
### Python Applications
96+
```
97+
# Build and test Python wordcount
98+
AlloyStack$ just python_wordcount
99+
100+
# Build and test Python parallel sort
101+
AlloyStack$ just python_parallel_sort
102+
103+
# Build and test Python long chain
104+
AlloyStack$ just python_long_chain
105+
```
106+
107+
## Comprehensive Build Scripts
108+
```
109+
# Build all Rust components
110+
AlloyStack$ just all_rust
111+
112+
# Build all C WASM applications
113+
AlloyStack$ just all_c_wasm
114+
115+
# Build all Python WASM applications
116+
AlloyStack$ just all_py_wasm
117+
118+
# Build all WASM applications
119+
AlloyStack$ just all_wasm
120+
121+
# Build and run all Rust tests
122+
AlloyStack$ just run_rust_test
123+
```
124+
## Environment Configuration
125+
### Build Flags
126+
127+
`enable_mpk` : Enable Memory Protection Keys
128+
129+
`enable_pkey_per_func` : Enable per-function protection keys
130+
131+
`enable_file_buffer` : Enable file-based buffering
132+
133+
`enable_release` : Build in release mode
134+
135+
# Helper Scripts
136+
These scripts are included in [AlloyStack/scripts](../scripts/) directory.
137+
138+
`build_all_common.sh` : Build common LibOS modules
139+
140+
`build_all_common_mpk.sh` : Build LibOS modules with MPK
141+
142+
`build_user.sh` : Build all user functions
143+
144+
`run_tests.sh` : Run test suite
145+
146+
`gen_data.py` : Generate test datasets
147+
148+
`clean_all.sh` : Delete files generated by compilation

‎doc/testing_a_workflow.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
## Testing a Workflow: map_reduce Example
2+
3+
To test a workflow in AlloyStack user need to go through the following steps. The same methodology applies to any workflow (e.g., Parallel Sort, Function Chain).
4+
5+
### Build System Services
6+
```
7+
# Build all required Libos services
8+
AlloyStack$ just all_libos
9+
```
10+
This command compiles essential system services: `fdtab` `stdio` `mm` `fatfs` `time`
11+
12+
### Build Workflow Functions
13+
```
14+
# Build each function in the workflow
15+
AlloyStack$ just rust_func file_reader
16+
AlloyStack$ just rust_func mapper
17+
AlloyStack$ just rust_func reducer
18+
```
19+
These commands compile the workflow's functional components: `file_reader` `mapper` `reducer`
20+
21+
### Execute the Workflow
22+
```
23+
# Run the map_reduce workflow
24+
AlloyStack$ target/release/asvisor --files isol_config/map_reduce.json
25+
```
26+
### Workflow Execution Process
27+
28+
#### Configuration (map_reduce.json)
29+
```
30+
{
31+
"groups": [
32+
// Stage 1: 3 file readers with different inputs
33+
{
34+
"list": [
35+
{"name": "file_reader", "args": {"slot_name": "part-0", "input_file": "fake_data_0.txt"}},
36+
{"name": "file_reader", "args": {"slot_name": "part-1", "input_file": "fake_data_1.txt"}},
37+
{"name": "file_reader", "args": {"slot_name": "part-2", "input_file": "fake_data_2.txt"}}
38+
]
39+
},
40+
// Stage 2: 3 parallel mappers
41+
{
42+
"list": ["mapper", "mapper", "mapper"],
43+
"args": {"reducer_num": "4"}
44+
},
45+
// Stage 3: 4 parallel reducers
46+
{
47+
"list": ["reducer", "reducer", "reducer", "reducer"],
48+
"args": {"mapper_num": "3"}
49+
}
50+
]
51+
}
52+
53+
# Stage 1: File Reading (Parallel)
54+
file_reader: slot_name: part-0
55+
file_reader: read_size=9881
56+
file_reader: slot_name: part-1
57+
file_reader: read_size=9951
58+
file_reader: slot_name: part-2
59+
file_reader: read_size=9903
60+
...
61+
# Stage 2: Map Processing (Parallel)
62+
mapper: The sum of all values is: 1194
63+
mapper: the counter nums is 825
64+
mapper: shuffle end, cost 0ms
65+
...
66+
# Stage 3: Reduce Processing (Parallel)
67+
reducer0 has counted 372 words
68+
reducer1 has counted 361 words
69+
reducer2 has counted 350 words
70+
reducer3 has counted 362 words
71+
...
72+
```
73+
74+
### Testing Other Workflows
75+
The same 3-step process applies to any workflow:
76+
77+
1.Build services: `just all_libos`
78+
79+
2.Build functions: `just rust_func <function_name>`
80+
81+
3.Execute workflow: `target/release/asvisor --files isol_config/<workflow_name>.json`

0 commit comments

Comments
 (0)