# Brainfuck with Syscall Extensions (BFA Mode) The `ewor_brainfuck` project introduces an extended Brainfuck interpreter mode known as Brainfuck with Syscall Extensions, or **BFA Mode**. This mode significantly enhances the capabilities of standard Brainfuck by allowing programs to interact with the underlying operating system through direct system calls (syscalls). This functionality is crucial for developing applications that require interaction with the system, such as networking (e.g., a [ping-pong server](/wiki/lantos1618/ewor_brainfuck/examples)) or file I/O. ## Enabling BFA Mode The `Mode::BFA` enum variant in `src/bf.rs` is responsible for activating this extended behavior within the `BF` interpreter. When you instantiate the `BF` interpreter, you can explicitly set it to `Mode::BFA`. The main executable (`src/main.rs`) automatically switches to `Mode::BFA` if the input Brainfuck file has a `.bfa` extension. If no extension is specified or it's `.bf`, it defaults to `Mode::BF`. However, it's generally recommended to use `.bfa` for files containing syscalls to ensure the correct interpreter mode is used. For more details on how to run programs in BFA mode, refer to the [Getting Started: Running Brainfuck and BFL](/wiki/lantos1618/ewor_brainfuck/getting-started) page. ## Syscall Convention In BFA mode, a specific memory layout is adopted to pass arguments to syscalls and retrieve their return values. This convention uses the initial cells of the Brainfuck memory tape: * **Cell 7**: Holds the **syscall number**. * **Cells 1-6**: Hold the **arguments** for the syscall, in order (arg1 in cell 1, arg2 in cell 2, etc.). A maximum of 6 arguments are supported. * **Cell 0**: Stores the **return value** of the syscall after execution. Any other memory cells can be used by the Brainfuck program as needed, but cells 0-7 are reserved for this syscall interface. ## The `.` Instruction in BFA Mode In standard Brainfuck, the `.` (dot) instruction prints the ASCII character value of the current cell. In BFA Mode, the behavior of the `.` instruction is **repurposed**. Instead of printing, it triggers the execution of a system call as defined by the values in cells 1-7. This means that to perform I/O like printing to stdout, you must use the `write` syscall instead of the traditional `.` instruction. This allows BFA programs to have fine-grained control over system interactions. ## Supported Syscalls The BFA interpreter supports a subset of common Linux/macOS system calls, allowing for basic file and network operations. These syscall numbers are defined in `src/syscall_consts.rs` to ensure portability between Linux and macOS. The `execute_bfa` function in `src/bf.rs` maps these numbers to the actual `syscalls` crate functions. The following syscalls are currently supported: * **`SYS_WRITE` (Syscall number 1 on Linux, 4 on macOS)** * **Purpose**: Writes data from a buffer to a file descriptor. * **Arguments**: * `arg1` (cell 1): File descriptor (e.g., 1 for stdout). * `arg2` (cell 2): Memory address (pointer) to the start of the data buffer. * `arg3` (cell 3): Number of bytes to write. * **Return Value (cell 0)**: Number of bytes written, or an error code. * *Example*: Writing "Hello" to stdout would involve setting `SYS_WRITE` in cell 7, `1` in cell 1 (stdout), the address of 'H' in cell 2, and `5` in cell 3, then executing `.`. * **`SYS_READ` (Syscall number 0 on Linux, 3 on macOS)** * **Purpose**: Reads data from a file descriptor into a buffer. * **Arguments**: * `arg1` (cell 1): File descriptor (e.g., 0 for stdin). * `arg2` (cell 2): Memory address (pointer) to the start of the buffer to read into. * `arg3` (cell 3): Maximum number of bytes to read. * **Return Value (cell 0)**: Number of bytes read, 0 for EOF, or an error code. * **`SYS_CLOSE` (Syscall number 3 on Linux, 6 on macOS)** * **Purpose**: Closes an open file descriptor. * **Arguments**: * `arg1` (cell 1): File descriptor to close. * **Return Value (cell 0)**: 0 on success, or an error code. * **`SYS_SOCKET` (Syscall number 41 on Linux, 97 on macOS)** * **Purpose**: Creates a new communication socket. * **Arguments**: * `arg1` (cell 1): Domain (e.g., `AF_INET` for IPv4). * `arg2` (cell 2): Type (e.g., `SOCK_STREAM` for TCP). * `arg3` (cell 3): Protocol (usually 0). * **Return Value (cell 0)**: New socket file descriptor, or an error code. * *Common constants*: `AF_INET = 2`, `SOCK_STREAM = 1`. * **`SYS_BIND` (Syscall number 49 on Linux, 104 on macOS)** * **Purpose**: Binds a socket to a local address and port. * **Arguments**: * `arg1` (cell 1): Socket file descriptor. * `arg2` (cell 2): Memory address (pointer) to the `sockaddr` structure. * `arg3` (cell 3): Length of the `sockaddr` structure. * **Return Value (cell 0)**: 0 on success, or an error code. * **`SYS_LISTEN` (Syscall number 50 on Linux, 106 on macOS)** * **Purpose**: Listens for incoming connections on a bound socket. * **Arguments**: * `arg1` (cell 1): Socket file descriptor. * `arg2` (cell 2): Backlog (maximum length of pending connections queue). * **Return Value (cell 0)**: 0 on success, or an error code. * **`SYS_ACCEPT` (Syscall number 43 on Linux, 30 on macOS)** * **Purpose**: Accepts a new connection on a listening socket. * **Arguments**: * `arg1` (cell 1): Listening socket file descriptor. * `arg2` (cell 2): Memory address (pointer) to a `sockaddr` structure to fill with client address info (can be 0/NULL). * `arg3` (cell 3): Memory address (pointer) to a `socklen_t` to fill with `sockaddr` length (can be 0/NULL). * **Return Value (cell 0)**: New client socket file descriptor, or an error code. ## Conceptual Brainfuck Syscall Snippet To illustrate how a syscall works directly in Brainfuck, consider writing a single character (e.g., 'A' which is ASCII 65) to standard output. Assume the Brainfuck program starts with its pointer at cell 0. The constants are: `SYS_WRITE` (Linux) = 1, `stdout` = 1. ```brainfuck +++++++ // Move pointer to cell 7 (syscall number) +++++++++ // Set cell 7 to 1 (SYS_WRITE) < // Move pointer to cell 6 (arg6) [-]< // Clear cells 6, 5, 4 (padding, ensure 0) [-]< [-] < // Move pointer to cell 3 (arg3: length) + // Set cell 3 to 1 (length of 1 byte) < // Move pointer to cell 2 (arg2: buffer address) ++++++++ // Set cell 2 to 8 (our message 'A' will be at cell 8) < // Move pointer to cell 1 (arg1: file descriptor) + // Set cell 1 to 1 (stdout) <<<<<<<< // Move pointer to cell 0 (return value) [-]> // Clear cell 0 (optional, but good practice) <++++++++ // Move pointer to cell 8 (where we'll put the character) +++++++++ // Set cell 8 to 65 ('A') >>>>>>>> // Move pointer to cell 7 (syscall number) . // Trigger the syscall! <<<<<<<< // Move pointer back to cell 0 to check return value (optional) ``` In this snippet: 1. We navigate to cell 7 and set it to `1` (for `SYS_WRITE`). 2. We clear cells 6, 5, 4 as they are unused for `SYS_WRITE`. 3. We set cell 3 (arg3, length) to `1`. 4. We set cell 2 (arg2, buffer address) to `8`, indicating that our character is stored at memory address 8. 5. We set cell 1 (arg1, file descriptor) to `1` (stdout). 6. We move the pointer to cell 8 and set its value to `65` (ASCII for 'A'). 7. Finally, we move the pointer back to cell 7 (where the syscall number is) and execute `.`, which triggers the `write` syscall. This direct Brainfuck implementation highlights the complexity of performing even simple operations. This is precisely why the [BFL (Brainfuck-like Language)](/wiki/lantos1618/ewor_brainfuck/bfl-reference) and its [compiler architecture](/wiki/lantos1618/ewor_brainfuck/bfl-compiler-architecture) were developed: to abstract away these low-level details and make complex programs, especially those involving syscalls and networking, more manageable. For practical examples showcasing BFA mode in action, refer to the [Practical Examples](/wiki/lantos1618/ewor_brainfuck/examples) page, particularly `examples/hello_bfl.rs`, `examples/syscall_print.rs`, and `examples/ping_pong_server.rs`.

Brainfuck with Syscall Extensions (BFA Mode)

Page Viewers

Guest Views