Formatting OFFS#

The mkfs.offs tool is used to format a block device storage into the OFFS file system.

Usage of mkfs.offs#

The format of the mkfs.offs command is as follows:

mkfs.offs [-v -f -s sectors_per_cluster -S sector_size -e] 
          <mmcblk path or mmcblk partition path> 
          <config file path> 
          <active format section name>

• The -v option prints verbose logs during the formatting process.
• The -f option performs a RAW format. It overwrites the MBR and creates a new partition table.
• The -s <sectors_per_cluster> option configures the number of sectors per cluster. Allowed values are powers of 2: 1, 2, 4, 8, 16, 32, 64, or 128.
• The -S <sector_size> option configures the sector size. The default value is 512 bytes. Allowed values are powers of 2: 512 (2^9), 1024, 2048, 4096, ..., up to 32768 (2^15). It might not be recognized depending on the system.
• The -e option is specified when formatting an external HDD or SSD storage device instead of an SD card.
• <mmcblk path or mmcblk partition path> is the first mandatory argument and represents the storage device path. If the -f option is specified, the block device path is specified for the RAW format. For example, it is "/dev/mmcblk0" in the case of an SD card.
• <config file path> is the second mandatory argument and represents the path to the format configuration file.
• <active format section name> is the third mandatory argument and represents the section name within the format configuration file to apply the actual format composition.

Format Configuration File#

mkfs.offs receives the configuration file path and the section name to be actually applied within that configuration file as arguments.

mkfs.offs proceeds with formatting using the folder structure and characteristics specified in this section.

The configuration file consists of a general section and multiple <user-defined sections>.

Lines starting with ; or # are comment lines.

general Section#

[general]
label=<volume label>
keep_root_files=<1 or 0>

• label: The volume label consisting of uppercase letters, up to 11 characters. If it is longer than 11 characters, formatting is canceled.
• keep_root_files * 1: Maintains existing files in the root folder as they are.
  • 0: Files in the root folder are also erased during formatting.

User-Defined Section#

The configuration file consists of one or more <user-defined sections>.

[section_name]
folders=<total number of folders>
mode=<mode>
signature=<signature>

folder<N>=<name>
folder<N>_size=<maximum file size>
folder<N>_percent=<allocation ratio>
folder<N>_mode=<mode>

• section_name: An arbitrary section name defined by the user. It must not contain spaces. It is case-insensitive.
• folders: The number of folders to create.
• mode: Specifies the purpose. Specify one of driving, parking, or general. This is purely for classification and has no effect on operation.
• signature: The signature name. It consists of up to 12 characters and spaces are not allowed. This is used to distinguish the section name to which formatting was applied.

Subsequent key values are prefixed with folder<N>_. <N> starts from 1 and increases by 1. The maximum value of <N> is the <total number of folders>.

• folder<N>: The folder name consisting of up to 11 characters. If it is longer than 11 characters, formatting is canceled.
• folder<N>_size: The maximum size of a file inside the folder, measured in MB. Configure this as a multiple of 4.
• folder<N>_percent: Specifies the total size occupied by this folder as a percentage relative to the total capacity.
• folder<N>_mode: The mode applied to this folder during formatting.
  • 0: Creates reserved files with a fixed maximum size. This is the default mode. It is suitable for storing recording files. You can have up to 4 folders of this type.
  • 1: Always creates a new folder if the folder exists. It does not create reserved files. It is an empty folder.
  • 2: Maintains files inside the folder without erasing them if the folder exists. Creates a new folder if the folder does not exist. It does not create reserved files. It is an empty folder. This is suitable for purposes like storing system configuration files or log records required for system operation.

Configuration File Example#

Below is an example of a configuration file having one user-defined section.

[general]
;DISK label (max 11 characters)
label=MYSD
;keep the files in the root directory
keep_root_files=1

;
; note: reserved file size should be multiple of 4.
;

[32GB_DRV]
;# of reserved folders.
;Max number of reserved folders is 4.
folders=6
;valid mode types: driving, parking, general
mode=driving
;signature (max 12-byte)
signature=32GB_DRV

;folder name. max 11 characters
folder1=DRIVING                
;file size in this folder. unit is MB.
folder1_size=180
folder1_percent=50
;mode 0: preserver files, 1:always new, 2: keep if exists;otherwise create
folder1_mode=0

folder2=PARKING
folder2_size=180
folder2_percent=20
folder2_mode=0

folder3=EVENT
folder3_size=24
folder3_percent=10
folder3_mode=0

folder4=MOTION
folder4_size=24
folder4_percent=10
folder4_mode=0

folder5=SNAPSHOT
folder5_size=4
folder5_percent=5
folder5_mode=1

folder6=Config
folder6_size=1
folder6_percent=5
folder6_mode=2

Examples of mkfs.offs Usage#

Below is an example of formatting an SD card using the configuration file above.

$ ./mkfs.offs /dev/mmcblk0p1 ./offs-format.cfg 32GB_DRV

OFFS Version 3.14.4(aarch64) (build 48643)
Free memory 852389888
label: MYSD
keep the root files: Yes
folders#: 6
mode: Driving
signature: 32GB_DRV
folder[0]: "DRIVING" 180MB 50% mode: PreserveFiles
folder[1]: "PARKING" 180MB 20% mode: PreserveFiles
folder[2]: "EVENT" 24MB 10% mode: PreserveFiles
folder[3]: "MOTION" 24MB 10% mode: PreserveFiles
folder[4]: "SNAPSHOT" 0MB 0% mode: AlwaysCreateNew
folder[5]: "Config" 0MB 0% mode: KeepIfExistsOtherwiseCreate
WR chunk 131072 buf 1024K
/dev/mmcblk0 readonly? 0
MBR fs 8160
PBR cl 16384, spc 32, bps 512
OFFS(ver. 3.14, type 1) detected
FAT 0x404000 0xb7c000 32 15296
DAT 0x12f4000 1 1
VOLUME: KL730
WR align 16384 chunk 131072
SIGNATURE: KL730
formatting...
disk size 32040288256 bytes (30556.00 MB, 29.84 GB)
root size 0 bytes (0.00 MB, 0.00 GB)
   DRIVING   50%   180 MB #85  
   PARKING   20%   180 MB #34  
     EVENT   10%    24 MB #128 
    MOTION   10%    24 MB #128 
  SNAPSHOT    0%     0 MB #0   
    Config    0%     0 MB #0   
    (free)        2992 MB
SUCCESS (22.050688 sec).

Below is an example of formatting an external hard disk (2TB).

$ sudo ./mkfs.offs -f -e /dev/sdk ./offs-format-gw-4ch.cfg driving

OFFS Version 3.13.20(x86_64) (build 42906)
Free memory 7048966144
warn: "/dev/sdk" path is not in mmcblk device path like /dev/mmcblk0. try to raw format the whole block device.
label: 4CH-CAR-DVR
keep the root files: Yes
folders#: 5
mode: Driving
signature: GW-4CH-DEV
folder[0]: "Drive" 356MB 35% mode: PreserveFiles
folder[1]: "Event" 124MB 20% mode: PreserveFiles
folder[2]: "Time Lapse" 168MB 35% mode: PreserveFiles
folder[3]: "DTG" 0MB 0% mode: AlwaysCreateNew
folder[4]: "Config" 0MB 0% mode: KeepIfExistsOtherwiseCreate
WR chunk 131072 buf 1024K
MBR fs 2016
MBR fs 8160
PBR cl 65536, spc 128, bps 512
FAT 0x800000 0x8000000 8192 245760
DAT 0xf800000 1 1
WR align 65536 chunk 131072
formatting...
disk size 2000394739200 bytes (1907725.12 MB, 1863.01 GB)
root size 0 bytes (0.00 MB, 0.00 GB)
     Drive   35%   356 MB #1876
     Event   20%   124 MB #3077
Time Lapse   35%   168 MB #3975
       DTG    0%     0 MB #0   
    Config    0%     0 MB #0   
    (free)       190521 MB
SUCCESS (2.059001 sec).