Constraints

S1 Router Programming Considerations

The S1 Router line has specific characteristics affecting Router App development, primarily related to its security model and read-only filesystem.

Extending the Read-Only Root Filesystem

On S1 Routers, the root filesystem is mounted read-only and cannot be directly modified. However, functionality can be extended using Router Apps, which are installed as read-only SquashFS overlays mounted over specific directories like /opt and potentially /usr.

Other writable partitions, such as the persistent /var and volatile /run and /tmp directories, are mounted with the "noexec" option. This prevents the execution of binaries directly from these locations. Therefore, executable files (binaries, scripts intended for direct execution) must be packaged within a Router App and placed in appropriate locations within the overlay (e.g., /opt//bin).

Examples example8 and example9 within the ModulesSDK demonstrate how to structure a Router App to add files to the /usr directory via the overlay mechanism. To build such an example (e.g., for the RBv2i-S1 platform):

cd modules/example8
make PLATFORM=RBv2i-S1

This build process generates a *.raw file. This .raw file is the Router App package for S1 platforms and can be installed using the standard Router App installation procedure in the web interface.

Adding JavaScript and CSS to the S1 Web Administration Interface

The S1 router's web server enforces a strict Content-Security-Policy (CSP). Inline JavaScript code and CSS styles are generally blocked unless specific mechanisms are used. To include custom JavaScript or CSS within web pages generated by your Router App (e.g., CGI scripts) on S1 routers, they must be embedded within or tags that include a dynamically generated nonce (number used once) attribute.

The ModulesSDK (version 2.1.1 and later) provides helper functions, um_html_js and um_html_css, designed to handle this correctly for C-based CGI. These functions automatically incorporate the required nonce when embedding scripts or styles. Example usage within a C-based CGI script using the SDK:

// Example: Set focus on the username field after the page loads
um_html_js("document.f.username.focus();\n");

// Example: Add a simple CSS rule
um_html_css(".my-class { color: blue; }\n");

For Python CGI scripts on S1, ensure your HTML generation logic can incorporate a nonce if provided by the system or the um Python module for S1.

Changing System Configuration Programmatically on S1 Routers

Configuration files on S1 Router line devices include an integrity check (checksum) to prevent unauthorized modifications. To change system configuration settings from within a Router App script, you cannot simply edit the configuration files directly. Instead, follow this procedure:

1. Create a partial configuration backup file (e.g., /tmp/backup.cfg) containing only the settings you wish to change, formatted correctly (e.g., SECTION_OPTION='value').
2. Calculate the SHA512 hash of this partial backup file and append it to the file itself in the format INTEGRITY=CFG_HASH=.
3. Use the restore command (with appropriate privileges, usually via sudo if available/required in the script context) to apply the changes from this integrity-checked partial backup file.

Example script snippet:

#!/bin/sh
# Create a temporary partial config file
cat  /tmp/backup.cfg
NETWORK_LAN_IPADDR='192.168.1.100'
NETWORK_LAN_NETMASK='255.255.255.0'
EOF

# Calculate hash and append integrity line
# Note: awk field might be $1 if output is just the hash
HASH_VAL=$(openssl sha512 /tmp/backup.cfg | awk '{print $2}')
echo "INTEGRITY=CFG_HASH=$HASH_VAL" >> /tmp/backup.cfg

# Apply the configuration change (requires appropriate permissions)
# The use of 'sudo' depends on the execution context of the script.
# If the script itself runs as root (e.g. some init scripts), sudo might not be needed.
# Otherwise, ensure the user/context has sudo rights for 'restore'.
sudo restore /tmp/backup.cfg

# Clean up temporary file
rm /tmp/backup.cfg

Note: Ensure the user/context running this script has permissions to execute sudo restore. The exact mechanism may vary depending on how your script is invoked by the system.

Hardware Constraints

Non-volatile Memory

Routers are embedded systems with limited resources. Efficient use of storage, RAM, and CPU is crucial.

Router Apps are installed in the /opt directory. Additionally, persistent data that needs to survive reboots but is generated or modified at runtime can often be stored in the /var/data directory. The type and size of non-volatile memory available for these directories vary depending on the router platform, as shown in the tables below.

Characteristics of the /var/data Directory Partition

Parameter	v2i	v2i with eMMC	v3	v3 with eMMC	v4	v4i
Memory type	NOR	eMMC	MRAM	eMMC	eMMC	eMMC
File system	JFFS2	ext4	JFFS2	ext4	ext4	ext4
Part. size	2 MiB	512 MiB	128 KiB	512 MiB	512 MiB	474 MiB

Characteristics of the /opt Directory Partition

Parameter	v2i	v2i with eMMC	v3	v3 with eMMC	v4	v4i
Memory type	NOR	eMMC	NOR	eMMC	eMMC	eMMC
File system	JFFS2	ext4	JFFS2	ext4	ext4	ext4
Part. size	12 MiB	814 MiB	128 MiB	838 MiB	838 MiB	2.16 GiB

Caution

On platforms where the /var/data partition uses MRAM and is 128 KiB in size (e.g., standard v3 routers), it is strongly recommended that a Router App uses no more than 64 KiB of this space. The remaining space is required by the router's operating system for its own persistent data storage.

Notes:

• The JFFS2 filesystem used on some NOR flash partitions supports compression. This means you might be able to store more data than the raw partition size suggests if the data compresses well.
• It is standard practice for a Router App needing persistent runtime data storage to create its own subdirectory within /var/data, e.g., /var/data/. This should typically be done in the install or init start script.
• The system typically automatically deletes the /var/data/ subdirectory (if it exists) when the corresponding Router App is uninstalled.
• Cleanup of any other files or subdirectories created by the Router App outside of /opt/ or /var/data/ is the responsibility of the Router App author (usually handled in the uninstall script).

RAM Utilization

Refer to the table below for the amount of RAM available on different router platforms. Router Apps can use standard dynamic memory allocation functions (e.g., malloc in C/C++, equivalent mechanisms in Python). Exercise caution regarding memory consumption; ensure your Router App does not deplete system memory, which could negatively impact router stability and performance.

RAM Memory Parameters

Parameter	v2i routers	v3 routers	v4 routers	v4i routers
RAM size	128 MB	512 MB	1024 MB	1024 MB

CPU Performance Considerations

There are CPU parameters for different router platforms listed in the table below. When developing applications consider these CPU constraints:

• Choose the development language appropriate for the task. C/C++ generally offers better performance for CPU-intensive operations than interpreted languages like Python or shell scripts.
• Avoid busy-waiting or tight loops that can consume excessive CPU.
• Offload complex computations to external systems if feasible and appropriate for your application.
• Profile your application if performance issues arise.

CPU Architecture

Parameter	v2i routers	v3 routers	v4 routers	v4i routers
CPU	SAM9X60	AM3352	ARMv8-A	ARMv8-A
Architecture	arm 5TEJ	arm v7	arm v8	arm v8
Core	ARM926EJ-S	Cortex-A8	Cortex-A72	Cortex-A53
CPU power	660 DMIPS	2000 DMIPS	4.7 DMIPS/MHz	2.3 DMIPS/MHz

Understanding Cross-Compilation and Compiler Flags

Cross-compilation is the process of compiling code on one system (the development host, e.g., x86 Linux) to run on a different system (the target router, e.g., ARM). This requires a toolchain (compiler, linker, libraries) built for the target architecture.

If you choose to use a different cross-compiler than the ones officially provided (see section on Toolchains), or if you need to fine-tune build parameters, ensure you use appropriate compiler flags for the target platform to generate compatible binaries. Based on the router platform, use the following flags:

v2i routers (ARMv5TEJ):

-march=armv5te -mtune=arm926ej-s  -mfloat-abi=soft

v3 routers (ARMv7-A / Cortex-A8):

-march=armv7-a -mtune=cortex-a8 -mfpu=vfpv3 -mfloat-abi=softfp

v4 routers (ARMv8-A / Cortex-A72):

-march=armv8-a+crc+crypto -mtune=cortex-a72

v4i routers (ARMv8-A / Cortex-A53):

-march=armv8-a+crc+crypto -mtune=cortex-a53