### Example objdump -h Output for DLL Sections

Source: https://github.com/bminor/newlib/blob/master/winsup/utils/ssp.txt

Illustrative output from objdump -h showing section headers, including the .text section's VMA, size, and attributes. This output helps identify the start and end addresses required by SSP for profiling a specific code segment.

```Text
cygwin1.dll:     file format pei-i386

Sections:
Idx Name          Size      VMA       LMA       File off  Algn
  0 .text         0007ea00  61001000  61001000  00000400  2**2
                  CONTENTS, ALLOC, LOAD, READONLY, CODE, DATA
  1 .data         00008000  61080000  61080000  0007ee00  2**2
                  CONTENTS, ALLOC, LOAD, DATA
  . . .
```

--------------------------------

### HOSTED_INIT_SIM Semihosting Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Initiates simulator-specific setup, such as allocating memory for the stack and heap. This request is typically invoked from startup code (e.g., crt0.S). On entry, d1 contains the default initial stack pointer value.

```APIDOC
HOSTED_INIT_SIM (request_code: 1)
  Parameters:
    d0: 1 (request code for simulator initialization)
    d1: default_initial_stack_pointer (immediate integer value)
  Returns:
    If simulator dynamically allocates memory: d1 and sp (a7) are updated to the new stack pointer value.
```

--------------------------------

### Example Gprof Report Output

Source: https://github.com/bminor/newlib/blob/master/winsup/utils/ssp.txt

A sample section from a gprof report, illustrating how instruction counts from SSP are presented as 'seconds' and 'ms/call'. This output shows the profiling results for individual functions, allowing identification of performance bottlenecks.

```Text
Each sample counts as 0.01 seconds.
  %   cumulative   self              self     total
 time   seconds   seconds    calls  ms/call  ms/call  name
 10.02    231.22    72.43       46  1574.57  1574.57  strcspn
  7.95    288.70    57.48      130   442.15   442.15  strncasematch
```

--------------------------------

### MetaWare Hostlink Library Component Overview

Source: https://github.com/bminor/newlib/blob/master/libgloss/arc/readme-hostlink.md

A description of the key files and modules within the MetaWare Hostlink library, outlining their purpose and interdependencies for hostlink message exchange, system call implementations, and low-level setup. This provides an architectural overview of the hostlink components.

```APIDOC
hl/hl_gw.*:
  - Hostlink gateway. This API is used in the hl_api.*.
  - Please use hl_message() from hl_api.* for hostlink message exchange.
hl/hl_api.*:
  - High-level API to send hostlink messages, as well as functions to work with messages.
hl/hl_<syscall>.*:
  - System calls implementations through hostlink API.
arc-timer.*:
  - Provides API to access ARC timers. Used by hl/hl_clock.c in _clock() implementation.
arc-main-helper.c:
  - Provides __setup_argv_and_call_main(). The function is called from __start() in crt0.S.
  - It allows to setup argc and arvg as well as some custom things through _setup_low_level().
hl-setup.c:
  - Provides _setup_low_level() for hostlink case. It just configures default timer if it exists.
  - Default timer is used in the hostlink clock() implementation.
hl-stub.c:
  - Provides functions which are part of newlib but implemented without hostlink.
  - For example, _kill() and _getpid().
sbrk.c:
  - Provides _sbrk(). It uses __start_heap and __end_heap variables.
libcfunc.c:
  - Additional C system calls.
mcount.c:
  - Profiler support.
```

--------------------------------

### Profile Entire Program with SSP

Source: https://github.com/bminor/newlib/blob/master/winsup/utils/ssp.txt

Command to run SSP for profiling an entire executable. It requires the start and end memory addresses of the code section (e.g., .text section VMA and its calculated end address) and the executable path. This operation generates a 'gmon.out' file containing profiling data.

```Shell
ssp 0x61001000 0x61080000 hello.exe
```

--------------------------------

### Cygwin GDB Debugging Wrapper Script

Source: https://github.com/bminor/newlib/blob/master/winsup/cygwin/DevDocs/how-to-debug-cygwin.txt

This batch script facilitates JIT (Just-In-Time) debugging for Cygwin applications. It sets the `CYGWIN_TESTING` environment variable to isolate the debugging session from other running Cygwin processes and then launches `gdb.exe`, attaching it to the crashed application.

```Batch
rem setting CYGWIN_TESTING environment variable makes cygwin application
rem not to interfere with other already running cygwin applications.
set CYGWIN_TESTING=1
c:\cygdeb\gdb.exe -nw %1 %2
```

--------------------------------

### Cygwin Early Startup Program Wrapper for Debugging

Source: https://github.com/bminor/newlib/blob/master/winsup/cygwin/DevDocs/how-to-debug-cygwin.txt

This batch script is designed to aid in debugging Cygwin applications that crash during their initial startup phase. It sets the `CYGWIN_SLEEP` environment variable, which causes the target application to pause for a specified duration (e.g., 20 seconds) at launch, providing a window to manually attach a debugger like GDB to its process ID.

```Batch
rem setting CYGWIN_SLEEP environment variable makes cygwin application
rem to sleep for x milliseconds at startup
set CYGWIN_SLEEP=20000
c:\some\path\bad_program.exe some parameters
```

--------------------------------

### Cygwin DLL Entry Point Call Sequence

Source: https://github.com/bminor/newlib/blob/master/winsup/cygwin/DevDocs/how-startup-shutdown-works.txt

This sequence illustrates the initial call flow for Cygwin-based DLLs. It starts with the __cygwin_dll_entry@12 entry point, which then delegates to cygwin_attach_dll. This function further calls _cygwin_crt0_common before handing off to dll_dllcrt0 within the Cygwin DLL. The user's DllMain may be called indirectly at a later stage.

```APIDOC
__cygwin_dll_entry@12 -> cygwin_attach_dll -> (_cygwin_crt0_common) -> dll_dllcrt0 -> (DllMain?maybe?)
```

--------------------------------

### Debugging strace *_printf Issues in GDB

Source: https://github.com/bminor/newlib/blob/master/winsup/cygwin/DevDocs/how-to-debug-cygwin.txt

Steps to debug `strace *_printf` issues by running an application under GDB, loading `cygwin1.dll`, setting a breakpoint, and enabling `strace` mode to identify incorrect format string usage that leads to crashes.

```bash
bash$ gdb -nw yourapp.exe
(gdb) dll cygwin1
(gdb) l dll_crt0_1
(gdb) b <<first line in the function>>
(gdb) run
(gdb) set strace._active=1
(gdb) continue
```

--------------------------------

### Nios II Semihosting: Get File Information by Descriptor (HOSTED_FSTAT)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for getting file information using a file descriptor, corresponding to the 'Ffstat' GDB fileio request. Parameters include file descriptor and a pointer to a stat buffer. Returns status and errno.

```APIDOC
#define HOSTED_FSTAT 10

  File information; 'Ffstat' GDB fileio request.
  
r5 points to a parameter block containing:
  [0] file descriptor
  [1] pointer to stat buf, using the structure definition in the GDB RSP
      documentation 

  Return values in parameter block:
  [0] return status
  [1] errno, encoded per the GDB RSP documentation
```

--------------------------------

### Nios II Semihosting: Get File Information (HOSTED_STAT)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for getting file information, corresponding to the 'Fstat' GDB fileio request. Parameters include filename pointer, length, and a pointer to a stat buffer. Returns status and errno.

```APIDOC
#define HOSTED_STAT 9

  File information; 'Fstat' GDB fileio request.

  r5 points to a parameter block containing:
  [0] filename pointer
  [1] filename length
  [2] pointer to stat buf, using the structure definition in the GDB RSP
      documentation 

  Return values in parameter block:
  [0] return status
  [1] errno, encoded per the GDB RSP documentation
```

--------------------------------

### Nios II Semihosting: Get Current Time (HOSTED_GETTIMEOFDAY)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for getting the current time, corresponding to the 'Fgettimeofday' GDB fileio request. Takes a timeval pointer in the parameter block. Returns status and errno.

```APIDOC
#define HOSTED_GETTIMEOFDAY 11

  Get current time; 'Fgettimeofday' GDB fileio request.

  r5 points to a parameter block containing:
  [0] timeval pointer, using the structure definition in the GDB RSP
      documentation

  Return values in parameter block:
  [0] return status
  [1] errno, encoded per the GDB RSP documentation
```

--------------------------------

### Basic C Program for Hostlink IO

Source: https://github.com/bminor/newlib/blob/master/libgloss/arc/readme-hostlink.md

A simple C program demonstrating a 'Hello, World!' message, intended to be compiled and run with the MetaWare hostlink library for interaction with nSIM/MDB. This program uses standard I/O functions.

```C
#include <stdio.h>

int main()
{
    printf("Hello, World!\n");
    return 0;
}
```

--------------------------------

### Execute SSP Utility with Verbose, Symbol, and DLL Options

Source: https://github.com/bminor/newlib/blob/master/winsup/utils/ssp.txt

This command demonstrates how to use the `ssp` utility with verbose output (`-v`), symbol information (`-s`), and DLL-specific analysis (`-dll`). It also specifies a memory range (`-d 0x61001000 0x61080000`) for analysis and the target executable (`hello.exe`). This configuration is particularly useful for profiling or debugging applications where performance bottlenecks might be located within loaded DLLs.

```Shell
ssp -v -s -dll -d 0x61001000 0x61080000 hello.exe
```

--------------------------------

### Build and Run C Program with MetaWare Hostlink on ARC Targets

Source: https://github.com/bminor/newlib/blob/master/libgloss/arc/readme-hostlink.md

Commands to compile a C program using `arc-elf32-gcc` or `arc64-elf-gcc` with the `hl.specs` for MetaWare hostlink, and then execute it on nSIM. This demonstrates the build and run process for various ARC HS targets (HS3x/4x, HS5x, HS6x), enabling hostlink communication.

```Shell
arc-elf32-gcc -mcpu=hs -specs=hl.specs hello.c -o hello.elf
nsimdrv -tcf $NSIM_HOME/etc/tcf/templates/hs48_full.tcf -p nsim_hostlink=1 hello.elf
```

```Shell
arc64-elf-gcc -mcpu=hs5x -specs=hl.specs hello.c -o hello.elf
nsimdrv -tcf $NSIM_HOME/etc/tcf/templates/hs58_full.tcf -p nsim_hostlink=1 hello.elf
```

```Shell
arc64-elf-gcc -mcpu=hs6x -specs=hl.specs hello.c -o hello.elf
nsimdrv -tcf $NSIM_HOME/etc/tcf/templates/hs68_full.tcf -p nsim_hostlink=1 hello.elf
```

--------------------------------

### Nios II Semihosting: Initialize Simulator (HOSTED_INIT_SIM)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for initializing the simulator. This operation is currently reserved and unimplemented.

```APIDOC
#define HOSTED_INIT_SIM 1

  Reserved/unimplemented.
```

--------------------------------

### GDB RSP Fisatty Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Documents the 'Fisatty' GDB file I/O request, identified by HOSTED_ISATTY, which checks if a given file descriptor corresponds to the GDB console. It outlines the input file descriptor and the return status.

```APIDOC
#define HOSTED_ISATTY 12

Fisatty GDB fileio request:
  Parameters (d1 parameter block):
    [0] file descriptor
  Return values (in parameter block):
    [0] return status
    [1] errno (encoded per GDB RSP documentation)
```

--------------------------------

### GDB RSP Fsystem Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Documents the 'Fsystem' GDB file I/O request, identified by HOSTED_SYSTEM, which executes a system command. It specifies the command pointer and length as inputs, along with the return status.

```APIDOC
#define HOSTED_SYSTEM 13

Fsystem GDB fileio request:
  Parameters (d1 parameter block):
    [0] command pointer
    [1] command length
  Return values (in parameter block):
    [0] return status
    [1] errno (encoded per GDB RSP documentation)
```

--------------------------------

### HOSTED_OPEN Semihosting Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Opens a file on the host system, corresponding to the 'Fopen' GDB fileio request. Parameters for the operation are provided in a 4-longword parameter block pointed to by register d1.

```APIDOC
HOSTED_OPEN (request_code: 2)
  Parameters:
    d0: 2 (request code for open file)
    d1: pointer_to_parameter_block (4-longword block)
      [0]: filename_pointer (pointer to filename string)
      [1]: filename_length (integer, length of filename string)
      [2]: open_flags (integer, encoded per GDB RSP documentation)
      [3]: mode (integer, encoded per GDB RSP documentation)
  Returns (in parameter block):
    [0]: file_descriptor (integer, -1 on error)
    [1]: errno (integer, encoded per GDB RSP documentation)
```

--------------------------------

### MetaWare Hostlink Communication Protocol

Source: https://github.com/bminor/newlib/blob/master/libgloss/arc/readme-hostlink.md

Detailed steps outlining the hostlink message exchange mechanism between the target program and the simulator/debugger. This includes the process of filling payload data, initializing packet and message headers, and the role of `_hl_blockedPeek()` for signaling and receiving responses, ensuring portable implementation.

```APIDOC
Simulator looks for __HOSTLINK__ and _hl_blockedPeek() symbols.
__HOSTLINK__ is the start of shared structure for message exchange.
_hl_blockedPeek() is a function to be called when program is waiting for simulator response.

When program wants to send a message it should follow:
1. Fill __HOSTLINK__.payload with packed data. Packing format: {u16 type, u16 size, char data[]}.
   Supported types: char, short, int, string, int64. hl_api provides high-level API to this.
2. Fill __HOSTLINK__.pkt_hdr. See hl_pkt_init() from hl_gw.c.
3. Fill __HOSTLINK__.hdr. See hl_send() from hl_gw.c.
4. Call _hl_blockedPeek() to get response. Message should be delivered to debugger.
   Portable implementation must fill __HOSTLINK__.hdr.target2host_addr at the last step and then call _hl_blockedPeek().
5. _hl_blockedPeek() returns pointer to debugger response (actually __HOSTLINK__.payload) which can be processed on target.
```

--------------------------------

### C Program for Selective SSP Profiling

Source: https://github.com/bminor/newlib/blob/master/winsup/utils/ssp.txt

A C program demonstrating how to use `OutputDebugString()` calls to control SSP's profiling scope. SSP will only profile the code executed between the 'ssp on' and 'ssp off' debug strings, allowing for focused analysis of specific code sections.

```C
#include <windows.h>
main()
{
  time_t t;
  OutputDebugString("ssp on");
  time(&t);
  OutputDebugString("ssp off");
}
```

--------------------------------

### Nios II Semihosting: Open File (HOSTED_OPEN)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for opening a file, corresponding to the 'Fopen' GDB fileio request. Parameters include filename, length, open flags, and mode, all passed via a parameter block pointed to by r5. Returns file descriptor or -1 on error, and errno.

```APIDOC
#define HOSTED_OPEN 2

  Open file; 'Fopen' GDB fileio request.

  r5 points to a parameter block containing:
  [0] pointer to filename
  [1] filename length
  [2] open flags, encoded per the GDB RSP documentation
  [3] mode, encoded per the GDB RSP documentation

  Return values in parameter block:
  [0] file descriptor or -1 on error
  [1] errno, encoded per the GDB RSP documentation
```

--------------------------------

### Generate Gprof Report from SSP Output

Source: https://github.com/bminor/newlib/blob/master/winsup/utils/ssp.txt

Command to process the 'gmon.out' file generated by SSP using gprof. The '-b' option skips the help pages, producing a readable performance report based on instruction counts, which are interpreted as 'seconds' by gprof.

```Shell
gprof -b cygwin1.dll
```

--------------------------------

### GDB 'Fsystem' File I/O Request Interface

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Specifies the parameter block and return values for the 'Fsystem' GDB file I/O request, detailing command pointer and length as inputs, and return status with errno as outputs.

```APIDOC
'Fsystem' GDB fileio request:

Input Parameters (r5 points to):
  [0] command pointer
  [1] command length

Return Values:
  [0] return status
  [1] errno, encoded per the GDB RSP documentation
```

--------------------------------

### Cygwin Executable Entry Point Call Sequence

Source: https://github.com/bminor/newlib/blob/master/winsup/cygwin/DevDocs/how-startup-shutdown-works.txt

This sequence details the startup flow for Cygwin-based executables. The standard Windows entry point WinMainCRTStartup (aliased to mainCRTStartup) initiates the process. It then calls cygwin_crt0, which in turn invokes _cygwin_crt0_common before transferring control to _dll_crt0 within the Cygwin DLL. The sequence continues through dll_crt0_1, potentially calling multiple DllMain functions, before finally entering the main function and concluding with cygwin_exit.

```APIDOC
mainCRTStartup -> cygwin_crt0 -> (_cygwin_crt0_common) -> _dll_crt0 -> dll_crt0_1 -> (n*DllMain?maybe?) -> main -> (__main) -> cygwin_exit
```

--------------------------------

### Selective Program Profiling with SSP -d Option

Source: https://github.com/bminor/newlib/blob/master/winsup/utils/ssp.txt

Command to run SSP with the '-d' option, which disables profiling by default. Profiling is then selectively enabled and disabled within the target program using `OutputDebugString()` calls, allowing for precise control over the profiled execution segments.

```Shell
ssp -d 0x61001000 0x61080000 hello.exe
```

--------------------------------

### HOSTED_WRITE Semihosting Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Writes data from a target buffer to an open file on the host system, corresponding to the 'Fwrite' GDB fileio request. Parameters include the file descriptor, buffer pointer, and byte count, passed via a block pointed to by d1.

```APIDOC
HOSTED_WRITE (request_code: 5)
  Parameters:
    d0: 5 (request code for write to file)
    d1: pointer_to_parameter_block (block)
      [0]: file_descriptor (integer)
      [1]: buffer_pointer (pointer to target buffer)
      [2]: byte_count (integer, number of bytes to write)
  Returns (in parameter block):
    [0]: bytes_written (integer, number of bytes actually written)
    [1]: errno (integer, encoded per GDB RSP documentation)
```

--------------------------------

### HOSTED_LSEEK Semihosting Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Performs a file seek operation on an open file, corresponding to the 'Flseek' GDB fileio request. The 64-bit offset and seek flag are passed via a parameter block pointed to by d1.

```APIDOC
HOSTED_LSEEK (request_code: 6)
  Parameters:
    d0: 6 (request code for file seek)
    d1: pointer_to_parameter_block (block)
      [0]: file_descriptor (integer)
      [1]: high_word_of_offset (high word of 64-bit offset)
      [2]: low_word_of_offset (low word of 64-bit offset)
      [3]: seek_flag (integer, encoded per GDB RSP documentation)
  Returns (in parameter block):
    [0]: high_word_of_result (high word of 64-bit result offset)
    [1]: low_word_of_result (low word of 64-bit result offset)
    [2]: errno (integer, encoded per GDB RSP documentation)
```

--------------------------------

### GDB RSP Ffstat Request (by file descriptor)

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Documents the 'Ffstat' GDB file I/O request, identified by HOSTED_FSTAT, which provides file information for a given file descriptor. It details the input parameters and the structure of the return values.

```APIDOC
#define HOSTED_FSTAT 10

Ffstat GDB fileio request:
  Parameters (d1 parameter block):
    [0] file descriptor
    [1] pointer to stat buf (using GDB RSP documentation structure)
  Return values (in parameter block):
    [0] return status
    [1] errno (encoded per GDB RSP documentation)
```

--------------------------------

### HOSTED_READ Semihosting Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Reads data from an open file on the host system into a buffer on the target, corresponding to the 'Fread' GDB fileio request. Parameters include the file descriptor, buffer pointer, and buffer size, passed via a block pointed to by d1.

```APIDOC
HOSTED_READ (request_code: 4)
  Parameters:
    d0: 4 (request code for read from file)
    d1: pointer_to_parameter_block (block)
      [0]: file_descriptor (integer)
      [1]: buffer_pointer (pointer to target buffer)
      [2]: buffer_size (integer, maximum bytes to read)
  Returns (in parameter block):
    [0]: bytes_read (integer, number of bytes actually read)
    [1]: errno (integer, encoded per GDB RSP documentation)
```

--------------------------------

### C Macro Definition for HOSTED_SYSTEM

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines a preprocessor macro `HOSTED_SYSTEM` with an integer value of 13, likely used for conditional compilation or system identification within the Newlib project.

```C
#define HOSTED_SYSTEM 13
```

--------------------------------

### GDB RSP Stat Request (by filename)

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Describes the common input parameters and return values for a GDB RSP stat-like operation that takes a filename as input, including filename length and a pointer to the stat buffer.

```APIDOC
Stat GDB fileio request (by filename):
  Parameters:
    [1] filename length
    [2] pointer to stat buf (using GDB RSP documentation structure)
  Return values (in parameter block):
    [0] return status
    [1] errno (encoded per GDB RSP documentation)
```

--------------------------------

### HOSTED_STAT Semihosting Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Retrieves information about a file on the host system, corresponding to the 'Fstat' GDB fileio request. The filename pointer is passed via a parameter block pointed to by d1. The full structure of return values is not detailed in the provided text.

```APIDOC
HOSTED_STAT (request_code: 9)
  Parameters:
    d0: 9 (request code for file information)
    d1: pointer_to_parameter_block (block)
      [0]: filename_pointer (pointer to filename string)
  Returns:
    (Details of return values not specified in input text)
```

--------------------------------

### GDB RSP Fgettimeofday Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Documents the 'Fgettimeofday' GDB file I/O request, identified by HOSTED_GETTIMEOFDAY, used to retrieve the current time. It specifies the required timeval pointer input and the return value structure.

```APIDOC
#define HOSTED_GETTIMEOFDAY 11

Fgettimeofday GDB fileio request:
  Parameters (d1 parameter block):
    [0] timeval pointer (using GDB RSP documentation structure)
  Return values (in parameter block):
    [0] return status
    [1] errno (encoded per GDB RSP documentation)
```

--------------------------------

### Generic System Call Parameter Block Definition

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the structure for a generic system call's input parameters and expected return values, including a file descriptor as input and return status with errno as output.

```APIDOC
Input Parameters (r5 points to):
  [0] file descriptor

Return Values:
  [0] return status
  [1] errno, encoded per the GDB RSP documentation
```

--------------------------------

### HOSTED_CLOSE Semihosting Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Closes an open file on the host system, corresponding to the 'Fclose' GDB fileio request. The file descriptor is passed via a parameter block pointed to by register d1.

```APIDOC
HOSTED_CLOSE (request_code: 3)
  Parameters:
    d0: 3 (request code for close file)
    d1: pointer_to_parameter_block (block)
      [0]: file_descriptor (integer)
  Returns (in parameter block):
    [0]: return_status (integer)
    [1]: errno (integer, encoded per GDB RSP documentation)
```

--------------------------------

### Nios II Semihosting: Read from File (HOSTED_READ)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for reading data from a file, corresponding to the 'Fread' GDB fileio request. Parameters include file descriptor, buffer pointer, and buffer size. Returns the number of bytes read and errno.

```APIDOC
#define HOSTED_READ 4

  Read from file; 'Fread' GDB fileio request.

  r5 points to a parameter block containing:
  [0] file descriptor
  [1] pointer to buffer
  [2] buffer size
  
  Return values in parameter block:
  [0] number of bytes read
  [1] errno, encoded per the GDB RSP documentation
```

--------------------------------

### HOSTED_EXIT Semihosting Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Terminates program execution on the target and sends a 'W' stop reply to GDB. This semihosting request is not expected to return to the caller. The exit code is passed directly as an immediate integer in register d1.

```APIDOC
HOSTED_EXIT (request_code: 0)
  Parameters:
    d0: 0 (request code for exit)
    d1: exit_code (immediate integer value)
  Returns:
    None (program terminates, does not return)
```

--------------------------------

### Nios II Semihosting: Write to File (HOSTED_WRITE)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for writing data to a file, corresponding to the 'Fwrite' GDB fileio request. Parameters include file descriptor, buffer pointer, and byte count. Returns the number of bytes written and errno.

```APIDOC
#define HOSTED_WRITE 5

  Write to file; 'Fwrite' GDB fileio request.

  r5 points to a parameter block containing:
  [0] file descriptor
  [1] pointer to buffer
  [2] byte count
  
  Return values in parameter block:
  [0] number of bytes written
  [1] errno, encoded per the GDB RSP documentation
```

--------------------------------

### Nios II Semihosting: File Seek (HOSTED_LSEEK)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for seeking within a file, corresponding to the 'Flseek' GDB fileio request. Parameters include file descriptor, 64-bit offset (high and low words), and seek flag. Returns the 64-bit result of the seek and errno.

```APIDOC
#define HOSTED_LSEEK 6

  File seek; 'Flseek' GDB fileio request.

  r5 points to a parameter block containing:
  [0] file descriptor
  [1] high word of 64-bit offset
  [2] low word of 64-bit offset
  [3] seek flag, encoded per the GDB RSP documentation

  Return values in parameter block:
  [0] high word of 64-bit result
  [1] low word of 64-bit result
  [2] errno, encoded per the GDB RSP documentation
```

--------------------------------

### Nios II Semihosting: Terminate Program Execution (HOSTED_EXIT)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for terminating program execution. It sends a 'W' stop reply to GDB. The exit code is passed directly in r5, and this request is not expected to return.

```APIDOC
#define HOSTED_EXIT  0

  Terminate program execution; send a 'W' stop reply to GDB.

  r5 contains the exit code, as an immediate integer rather than indirectly
  in a parameter block.  This semihosting request isn't expected to return.
```

--------------------------------

### HOSTED_RENAME Semihosting Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Renames a file on the host system, corresponding to the 'Frename' GDB fileio request. Pointers and lengths for both the old and new filenames are passed via a parameter block pointed to by d1.

```APIDOC
HOSTED_RENAME (request_code: 7)
  Parameters:
    d0: 7 (request code for rename file)
    d1: pointer_to_parameter_block (block)
      [0]: oldname_pointer (pointer to old filename string)
      [1]: oldname_length (integer, length of old filename string)
      [2]: newname_pointer (pointer to new filename string)
      [3]: newname_length (integer, length of new filename string)
  Returns (in parameter block):
    [0]: return_status (integer)
    [1]: errno (integer, encoded per GDB RSP documentation)
```

--------------------------------

### Nios II Semihosting: Close File (HOSTED_CLOSE)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for closing a file, corresponding to the 'Fclose' GDB fileio request. Takes a file descriptor in the parameter block. Returns status and errno.

```APIDOC
#define HOSTED_CLOSE 3

  Close file; 'Fclose' GDB fileio request.

  r5 points to a parameter block containing:
  [0] file descriptor

  Return values in parameter block:
  [0] return status
  [1] errno, encoded per the GDB RSP documentation
```

--------------------------------

### Cygwin DLL Unload Call Sequence

Source: https://github.com/bminor/newlib/blob/master/winsup/cygwin/DevDocs/how-startup-shutdown-works.txt

This sequence outlines the termination process for Cygwin-based DLLs. It begins with the _cygwin_dll_entry@12 function, which then calls the DllMain function for process detach. This is followed by cygwin_detach_dll, which leads to dll_list::detach. The sequence concludes with remove_dll_atexit and dll::run_dtors to handle cleanup and destructor execution.

```APIDOC
_cygwin_dll_entry@12 -> (DllMain) -> cygwin_detach_dll -> dll_list::detach -> (remove_dll_atexit) -> (dll::run_dtors)
```

--------------------------------

### Generate C Timezone Map from Unicode XML and Custom Additions

Source: https://github.com/bminor/newlib/blob/master/winsup/utils/tzmap-from-unicode.org

This Bash script fetches the `windowsZones.xml` file from unicode.org, processes it using `sed` to extract and transform timezone mappings, and then appends several hardcoded, missing, or deprecated Windows timezone entries. The final output is a C-style array `tzmap` that maps Windows timezone keynames and countries to POSIX timezone IDs, sorted alphabetically. This generated C code is intended for use by `tzset.c`.

```bash
#!/bin/bash
#
# tzset-from-unicode.org
#
# Fetch XML file containing mapping of Windows timezone keynames and countries
# per ISO 3166-1 to POSIX timezones from unicode.org.
#
# Create the table file as required by tzset.c.
#

ZONES_FILE="https://raw.githubusercontent.com/unicode-org/cldr/master/common/supplemental/windowsZones.xml"

echo "/*"
echo "   This file gets auto-generated by the script tzmap-from-unicode.org via"
echo "   a Makefile rule.  To regenerate the file, just call 'make tzmap'.  It"
echo "   fetches the file"
echo ""
echo "     ${ZONES_FILE}"
echo ""
echo "   using wget and converts it into the tzmap table required by tzget.c."
echo "   Regenerating might be necessary on a regular basis..."
echo ""
echo "   This table maps Windows timezone keynames and countries per ISO 3166-1 to"
echo "   POSIX-compatible timezone IDs."
echo ""
echo "   The mapping from unicode.org is just a bit incomplete.  It doesn't contain"
echo "   some (deprecated) timezones available since Windows 8.1:"
echo ""
echo "    Mid-Atlantic Standard Time"
echo "    Kamchatka Standard Time"
echo ""
echo "  as well as a few combinations which got a new Windows timezone name"
echo "  but may still be in use somewhere..."
echo ""
echo "    E. Europe Standard Time/CY"
echo "    Eastern Standard Time/TC"
echo "    Egypt Standard Time/PS"
echo "    Greenwich Standard Time/EH"
echo "    Hawaiian Standard Time/TK"
echo "    Kaliningrad Standard Time/BY"
echo "    SA Pacific Standard Time/HT "
echo "    South Africa Standard Time/LY"
echo "*/"
echo ""
echo "struct"
echo "{"
echo "  PCWSTR win_tzkey;"
echo "  PCWSTR country;"
echo "  PCWSTR posix_tzid;"
echo "} const tzmap[] ="
echo "{"
wget -O - "${ZONES_FILE}" | \
{
  sed -n -e 's#territory="001"#territory=""#\
	     s#Asia/Calcutta#Asia/Kolkata#\
	     .*mapZone other=\("[^"]*"\) territory=\("[^"]*"\) type=\("[^"]*"\).*#  { L\1, L\2, L\3 },#p'
  echo '  { L"E. Europe Standard Time", L"CY", L"Asia/Nicosia" },'
  echo '  { L"Eastern Standard Time", L"TC", L"America/Grand_Turk" },'
  echo '  { L"Egypt Standard Time", L"PS", L"Asia/Gaza Asia/Hebron" },'
  echo '  { L"Greenwich Standard Time", L"EH", L"Africa/El_Aaiun" },'
  echo '  { L"Kaliningrad Standard Time", L"BY", L"Europe/Minsk" },'
  echo '  { L"Kamchatka Standard Time", L"", L"Asia/Kamchatka" },'
  echo '  { L"Hawaiian Standard Time", L"TK", L"Pacific/Fakaofo" },'
  echo '  { L"Mid-Atlantic Standard Time", L"", L"Atlantic/South_Georgia" },'
  echo '  { L"SA Pacific Standard Time", L"HT", L"America/Port-au-Prince" },'
  echo '  { L"South Africa Standard Time", L"LY", L"Africa/Tripoli" },'
} | LC_ALL=C sort -d
echo "};"
```

--------------------------------

### GDB Command to Inspect Windows Thread Information Block (TIB)

Source: https://github.com/bminor/newlib/blob/master/winsup/cygwin/DevDocs/how-cygtls-works.txt

This GDB command, info w32 tib, allows developers to examine the contents of the Windows Thread Information Block (TIB) during a debugging session. It provides insight into the current thread's context, including stack pointers and other thread-specific data relevant to Cygwin's TLS implementation.

```GDB
info w32 tib
```

--------------------------------

### Cygwin `_lseek` System Call Implementation

Source: https://github.com/bminor/newlib/blob/master/winsup/cygwin/DevDocs/how-fhandlers-work.txt

This C++ code snippet illustrates the implementation of the `_lseek` system call within the Cygwin environment. It demonstrates how file descriptor operations are routed through the `fhandler` mechanism. The function validates input parameters (`dir` and `fd` status) before delegating the actual seek operation to the `lseek` virtual function of the `fhandler` associated with the given file descriptor. It returns the new offset or -1 on error, setting `errno` accordingly.

```C++
extern "C" off_t
_lseek (int fd, off_t pos, int dir)
{
  off_t res;
  sigframe thisframe (mainthread);

  if (dir != SEEK_SET && dir != SEEK_CUR && dir != SEEK_END)
    {
      set_errno (EINVAL);
      res = -1;
    }
  else if (cygheap->fdtab.not_open (fd))
    {
      set_errno (EBADF);
      res = -1;
    }
  else
    {
      res = cygheap->fdtab[fd]->lseek (pos, dir);
    }
  syscall_printf ("%d = lseek (%d, %d, %d)", res, fd, pos, dir);

  return res;
}
```

--------------------------------

### HOSTED_UNLINK Semihosting Request

Source: https://github.com/bminor/newlib/blob/master/libgloss/m68k/m68k-semi.txt

Deletes (unlinks) a file on the host system, corresponding to the 'Funlink' GDB fileio request. The filename pointer and length are passed via a parameter block pointed to by d1.

```APIDOC
HOSTED_UNLINK (request_code: 8)
  Parameters:
    d0: 8 (request code for unlink file)
    d1: pointer_to_parameter_block (block)
      [0]: filename_pointer (pointer to filename string)
      [1]: filename_length (integer, length of filename string)
  Returns (in parameter block):
    [0]: return_status (integer)
    [1]: errno (integer, encoded per GDB RSP documentation)
```

--------------------------------

### Nios II Semihosting: Rename File (HOSTED_RENAME)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for renaming a file, corresponding to the 'Frename' GDB fileio request. Parameters include pointers and lengths for both old and new filenames. Returns status and errno.

```APIDOC
#define HOSTED_RENAME 7

  File rename; 'Frename' GDB fileio request.

  r5 points to a parameter block containing:
  [0] oldname pointer
  [1] oldname length
  [2] newname pointer
  [3] newname length

  Return values in parameter block:
  [0] return status
  [1] errno, encoded per the GDB RSP documentation
```

--------------------------------

### Determine .text Section Bounds with objdump

Source: https://github.com/bminor/newlib/blob/master/winsup/utils/ssp.txt

Use the objdump utility to inspect the section headers of a DLL, specifically to find the Virtual Memory Address (VMA) and size of the .text section. This information is crucial for defining the memory range for SSP profiling.

```Shell
objdump -h cygwin1.dll
```

--------------------------------

### Nios II Semihosting: Unlink File (HOSTED_UNLINK)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for unlinking/deleting a file, corresponding to the 'Funlink' GDB fileio request. Parameters include filename pointer and length. Returns status and errno.

```APIDOC
#define HOSTED_UNLINK 8

  File unlink/delete; 'Funlink' GDB fileio request.

  r5 points to a parameter block containing:
  [0] filename pointer
  [1] filename length

  Return values in parameter block:
  [0] return status
  [1] errno, encoded per the GDB RSP documentation
```

--------------------------------

### Windows NT_TIB Structure Definition for Thread Context

Source: https://github.com/bminor/newlib/blob/master/winsup/cygwin/DevDocs/how-cygtls-works.txt

Defines the _NT_TIB structure, a fundamental Windows data structure representing the Thread Information Block (TIB). It contains critical thread-specific data such as exception list pointers, stack base and limit addresses, and a self-reference, which Cygwin utilizes for TLS management.

```C
typedef struct _NT_TIB {
	struct _EXCEPTION_REGISTRATION_RECORD *ExceptionList;
	PVOID StackBase;
	PVOID StackLimit;
	PVOID SubSystemTib;
	_ANONYMOUS_UNION union {
		PVOID FiberData;
		DWORD Version;
	} DUMMYUNIONNAME;
	PVOID ArbitraryUserPointer;
	struct _NT_TIB *Self;
} NT_TIB,*PNT_TIB;
```

--------------------------------

### Cygwin Autoloading Macro: LoadDLLfuncEx2 Signature

Source: https://github.com/bminor/newlib/blob/master/winsup/cygwin/DevDocs/how-autoload-works.txt

Defines the signature and behavior of the `LoadDLLfuncEx2` macro, which is used in `autoload.cc` to configure how specific Win32 functions are handled by Cygwin's dynamic autoloading mechanism, including error handling options.

```APIDOC
LoadDLLfuncEx2(
  function name: string,
  parameter block length: int,
  dll name: string,
  non-fatality flag: int,
  value to return if function not available: any
)

Parameters:
  parameter block length: Sum of sizes (in bytes) of parameters which are being passed to the function.
  non-fatality flag:
    0: Failure to load DLL and find a function will cause fatal error.
    1: Call to the function will return default value.
```

--------------------------------

### Nios II Semihosting: Check if File Descriptor is TTY (HOSTED_ISATTY)

Source: https://github.com/bminor/newlib/blob/master/libgloss/nios2/nios2-semi.txt

Defines the request code for checking if a file descriptor refers to the GDB console, corresponding to the 'Fisatty' GDB fileio request. Returns true if it is the GDB console.

```APIDOC
#define HOSTED_ISATTY 12

 Return true if the file descriptor is the GDB console; 'Fisatty' GDB fileio
 request.
```

--------------------------------

### Cygwin Macro for _cygtls Object Access

Source: https://github.com/bminor/newlib/blob/master/winsup/cygwin/DevDocs/how-cygtls-works.txt

The _my_tls macro provides a mechanism for Cygwin threads to access their _cygtls object. It computes the object's memory address by subtracting __CYGTLS_PADSIZE__ from the StackBase address obtained from the current thread's TIB, enabling efficient thread-local data retrieval.

```C
#define _my_tls (*((_cygtls *) ((PBYTE) NtCurrentTeb()->Tib.StackBase \
		                - __CYGTLS_PADSIZE__)))
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.