Skip to content

Commit d4d5516

Browse files
author
Felix "xq" Queißner
committed
Updates README.
1 parent 5c254b1 commit d4d5516

File tree

1 file changed

+105
-8
lines changed

1 file changed

+105
-8
lines changed

‎README.md

+105-8
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1-
# Disk Image Creator
1+
# 💡 Dimmer - The Disk Imager
22

3-
The Disk Image Creator is a tool that uses a simple textual description of a disk image to create actual images.
3+
> *Realize bright ideas with less energy!*
44
5-
This tool is incredibly valuable when implementing your own operating system or deployments.
5+
Dimmer is a tool that uses a simple textual description of a disk image to create actual images.
6+
7+
This tool is incredibly valuable when implementing your own operating system, embedded systems or other kinds of deployment.
68

79
## Example
810

@@ -12,10 +14,6 @@ This tool is incredibly valuable when implementing your own operating system or
1214

1315
## Available Content Types
1416

15-
```plain
16-
17-
```
18-
1917
### Empty Content (`empty`)
2018

2119
This type of content does not change its range at all and keeps it empty. No bytes will be emitted.
@@ -45,23 +43,122 @@ paste-file <path>
4543
### MBR Partition Table (`mbr-part`)
4644

4745
```plain
46+
mbr-part
47+
[bootloader <content>]
48+
[part <…> | ignore] # partition 1
49+
[part <…> | ignore] # partition 2
50+
[part <…> | ignore] # partition 3
51+
[part <…> | ignore] # partition 4
52+
```
4853

54+
```plain
55+
part
56+
type <type-id>
57+
[bootable]
58+
[size <bytes>]
59+
[offset <bytes>]
60+
contains <content>
61+
endpart
4962
```
5063

64+
If `bootloader <content>` is given, will copy the `<content>` into the boot block, setting the boot code.
65+
66+
The `mbr-part` component will end after all 4 partitions are specified.
67+
68+
- Each partition must specify the `<type-id>` (see table below) to mark the partition type as well as `contains <content>` which defines what's stored in the partition.
69+
- If `bootable` is present, the partition is marked as bootable.
70+
- `size <bytes>` is required for all but the last partition and defines the size in bytes. It can use disk-size specifiers.
71+
- `offset <bytes>` is required for either all or no partition and defines the disk offset for the partitions. This can be used to explicitly place the partitions.
72+
73+
#### Partition Types
74+
75+
| Type | ID | Description |
76+
| ------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
77+
| `empty` | 0x00 | No content |
78+
| `fat12` | 0x01 | [FAT12](https://en.wikipedia.org/wiki/FAT12) |
79+
| `ntfs` | 0x07 | [NTFS](https://en.wikipedia.org/wiki/NTFS) |
80+
| `fat32_chs` | 0x0B | [FAT32](https://en.wikipedia.org/wiki/FAT32) with [CHS](https://en.wikipedia.org/wiki/Cylinder-head-sector) addressing |
81+
| `fat32_lba` | 0x0C | [FAT32](https://en.wikipedia.org/wiki/FAT32) with [LBA](https://en.wikipedia.org/wiki/Logical_block_addressing) addressing |
82+
| `fat16_lba` | 0x0E | [FAT16B](https://en.wikipedia.org/wiki/File_Allocation_Table#FAT16B) with [LBA](https://en.wikipedia.org/wiki/Logical_block_addressing) addressing |
83+
| `linux_swap` | 0x82 | [Linux swap space](https://en.wikipedia.org/wiki/Swap_space#Linux) |
84+
| `linux_fs` | 0x83 | Any [Linux file system](https://en.wikipedia.org/wiki/File_system#Linux) |
85+
| `linux_lvm` | 0x8E | [Linux LVM](https://en.wikipedia.org/wiki/Logical_Volume_Manager_(Linux)) |
86+
87+
A complete list can be [found on Wikipedia](https://en.wikipedia.org/wiki/Partition_type), but [we do not support that yet](https://github.com/zig-osdev/disk-image-step/issues/8).
88+
5189
### GPT Partition Table (`gpt-part`)
5290

5391
```plain
5492
5593
```
5694

57-
### FAT File System (`fat`)
95+
### FAT File System (`vfat`)
5896

5997
```plain
98+
vfat <type>
99+
[label <fs-label>]
100+
[fats <fatcount>]
101+
[root-size <count>]
102+
[sector-align <align>]
103+
[cluster-size <size>]
104+
<fs-ops...>
105+
endfat
106+
```
107+
108+
| Parameter | Values | Description |
109+
| ------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
110+
| `<type>` | `fat12`, `fat16`, `fat32` | Selects the type of FAT filesystem that is created |
111+
| `<fatcount>` | `one`, `two` | Number of FAT count. Select between small and safe. |
112+
| `<fs-label>` | ascii string <= 11 chars | Display name of the volume. |
113+
| `<count>` | integers <= 32768 | Number of entries in the root directory. |
114+
| `<align>` | power of two >= 1 and <= 32768 | Specifies alignment of the volume data area (file allocation pool, usually erase block boundary of flash memory media) in unit of sector. The valid value for this member is between 1 and 32768 inclusive in power of 2. If a zero (the default value) or any invalid value is given, the function obtains the block size from lower layer with disk_ioctl function. |
115+
| `<size>` | powers of two | Specifies size of the allocation unit (cluter) in unit of byte. |
60116

117+
## Standard Filesystem Operations
118+
119+
All `<path>` values use an absolute unix-style path, starting with a `/` and using `/` as a file separator.
120+
121+
All operations do create the parent directories if necessary.
122+
123+
### Create Directory (`mkdir`)
124+
125+
```plain
126+
mkdir <path>
61127
```
62128

129+
Creates a directory.
130+
131+
### Create File (`create-file`)
132+
133+
```plain
134+
create-file <path> <size> <content>
135+
```
136+
137+
Creates a file in the file system with `<size>` bytes (can use sized spec) and embeds another `<content>` element.
138+
139+
This can be used to construct special or nested files ad-hoc.
140+
141+
### Copy File (`copy-file`)
142+
143+
```plain
144+
copy-file <path> <host-path>
145+
```
146+
147+
Copies a file from `<host-path>` (relative to the current file) into the filesystem at `<path>`.
148+
149+
### Copy Directory (`copy-dir`)
150+
151+
```plain
152+
copy-file <path> <host-path>
153+
```
154+
155+
Copies a directory from `<host-path>` (relative to the current file) *recursively* into the filesystem at `<path>`.
156+
157+
This will include *all files* from `<host-path>`.
158+
63159
## Compiling
64160

161+
65162
- Install [Zig 0.14.0](https://ziglang.org/download/).
66163
- Invoke `zig build -Drelease` in the repository root.
67164
- Execute `./zig-out/bin/dim --help` to verify your compilation worked.

0 commit comments

Comments
 (0)