# What's New In This Release

## Highlights
* Feature 1
* Feature 2
* Feature 3

## Major Changes to Core OS

### New Features

### Bug Fixes

## Major Changes to the Build System

### New Features

### Bug Fixes

## Architectural Support

### New Architecture

### Architectures with significant improvements

#### ARM

#### CXD56XX

#### STM32

#### STM32L4

#### STM32L5

#### S32K1XX

#### IMX6

#### IMXRT

#### RP2040  

#### NRF52

#### STM32H7

#### STM32F7

#### Renesas

#### RX65N

#### Risc-V

#### RV64

#### ESP32C3

#### BL602

#### Xtensa

#### ESP32

### Minor changes

## Simulator

### New Features

### Bug Fixes

## Documentation

### New Features

### Improvements

## Driver Support

### Bug Fixes

### New Driver Support

## Board Support

### New Board Support

### Boards With Significant Improvements

#### ARM

#### CXD56

#### IMX6

#### IMXRT  

#### LPC17XX_40XX

#### NRF52

#### RP2040

#### SAM34

#### STM32  

#### STM32L4

#### STM32F4

#### STM32F7

#### STM32H7

#### KINETIS

#### RISC-V

#### BL602

#### C906

#### ESP32C3

#### XTENSA

#### ESP32

#### TIVA

### **Minor Board Changes**

#### ARM  

#### CXD56  

#### Xtensa

## File System

### Bug Fixes

### Significant Improvements

## Networking

### Improvements

### Bug Fixes

# Security Issues Fixed In This Release

# Compatibility Concerns

## Changes to Kconfig

The names of some Kconfig settings have been changed to improve the naming consistency. Here is the list:

| Old                | New                 |
|:------------------:| -----------------:  |
|LIB_BOARDCTL        |BOARDCTL             |
|LIB_CRC64_FAST      |LIBC_CRC64_FAST      |
|LIB_ENVPATH         |LIBC_ENVPATH         |
|LIB_HEX2BIN         |LIBC_HEX2BIN         |
|LIB_HOMEDIR         |LIBC_HOMEDIR         |
|LIB_HOSTNAME        |LIBC_HOSTNAME        |
|LIB_KBDCODEC        |LIBC_KBDCODEC        |
|LIB_RAND_ORDER      |LIBC_RAND_ORDER      |
|LIB_SLCDCODEC       |LIBC_SLCDCODEC       |
|LIB_USRWORK         |LIBC_USRWORK         |
|LIB_USRWORKPRIORITY |LIBC_USRWORKPRIORITY |
|LIB_USRWORKSTACKSIZE|LIBC_USRWORKSTACKSIZE|
|LIB_ZONEINFO        |LIBC_ZONEINFO        |
|LIB_ZONEINFO_ROMFS  |LIBC_ZONEINFO_ROMFS  |

When they appear in code, these identifiers begin with a `CONFIG_*` prefix (e.g., `CONFIG_LIB_BOARDCTL` is renamed to `CONFIG_BOARDCTL`).

All in-tree boards have been updated, but users who maintain their own out-of-tree boards will have to update all instances of these identifiers.

See PR-4266 https://github.com/apache/incubator-nuttx/pull/4266 and PR-4267 https://github.com/apache/incubator-nuttx/pull/4267 in the main NuttX repository.

See also PR-820 https://github.com/apache/incubator-nuttx-apps/pull/820 and PR-821 https://github.com/apache/incubator-nuttx-apps/pull/821 in the NuttX apps repository.

## Changes to Build System

### LD Now Called Through GCC

When building NuttX with GCC toolchains, the linker is now called through $(CROSSDEV)gcc rather than $(CROSSDEV)ld. This requires all linker options to be prefixed with `-Wl,` (dash, capital W, lower-case L, comma). All boards in the NuttX tree have been updated, but any custom out-of-tree boards will need to apply this change in the relevant parts of their build scripts.

The reason for this change is that GNU Binutils 2.36.x has added new error checking on command line arguments. This has had the effect that the NuttX build suddenly broke on host OS distributions that updated to the 2.36.x release line. Reports included Arch, Manjaro, and Ubuntu. Other host OSes are likely to be affected as well.

#### Symptoms

Your toolchain and board are affected if you see errors from LD like:

```
arm-none-eabi-ld: Error: unable to disambiguate: -nostartfiles (did you mean --nostartfiles ?)
```

or (following this change in NuttX) errors from GCC like:

```
arm-none-eabi-gcc: error: unrecognized command line option '--gc-sections'; did you mean '--data-sections'?
```

#### What to change

The most common change expected to affect most boards:

Change:

```
NXFLATLDFLAGS1 = -r -d -warn-common
NXFLATLDFLAGS2 = $(NXFLATLDFLAGS1) -T$(TOPDIR)/binfmt/libnxflat/gnu-nxflat-pcrel.ld -no-check-sections
```

to:

```
NXFLATLDFLAGS1 = -r -Wl,-d -Wl,-warn-common
NXFLATLDFLAGS2 = $(NXFLATLDFLAGS1) -T$(TOPDIR)/binfmt/libnxflat/gnu-nxflat-pcrel.ld -Wl,-no-check-sections
```

If doing a kernel build, you may need changes in your board's `kernel/Makefile` like:

Change:

```
USER_LDFLAGS = --undefined=$(ENTRYPT) --entry=$(ENTRYPT) $(USER_LDSCRIPT)
```

to:

```
USER_LDFLAGS = -Wl,--undefined=$(ENTRYPT) -Wl,--entry=$(ENTRYPT) $(USER_LDSCRIPT) -nostartfiles -nodefaultlibs
```

Change:
 
```
$(Q) $(LD) -o $@ $(USER_LDFLAGS) $(USER_LIBPATHS) $(OBJS) --start-group $(USER_LDLIBS) --end-group $(USER_LIBGCC)
```

to:

```
$(Q) $(LD) -o $@ $(USER_LDFLAGS) $(USER_LIBPATHS) $(OBJS) -Wl,--start-group $(USER_LDLIBS) -Wl,--end-group $(USER_LIBGCC)
```

Depending on your board's customized build scripts, you may need to look out for other `make` variables in your board's `Makefile` or `Make.defs`.

Some variables to look for:

- `ARCHSCRIPT`
- `ARCH_LIBS`
- `CCLINKFLAGS`
- `EXTRALINKCMDS`
- `LDELFFLAGS`
- `LDENDGROUP`
- `LDFLAGS`
- `LDLINKFLAGS`
- `LDMODULEFLAGS`
- `LDSTARTGROUP`
- `NXFLATLDFLAGS1`
- `NXFLATLDFLAGS2`
- `USER_LDFLAGS`

Anything that executes LD, such as:

```
$(Q) $(LD) --entry=__start $(LDFLAGS) $(LIBPATHS) $(EXTRA_LIBPATHS) \
```

Anything that processes LD flags, such as:

```
$(LIBPATHS) "-(" $(LDLIBS) "-)" $(LDFLAGS) -Map="$(TOPDIR)$(DELIM)nuttx.map"
```

In general, any command line options destined for LD must be prefixed with `-Wl,` (dash, capital W, lower-case L, comma) since they are now being passed through GCC.

#### Examples

Change:

```
EXTRALINKCMDS += @$(TOPDIR)/syscall/syscall_wraps.ldcmd
```

to:

```
EXTRALINKCMDS += -Wl,@$(TOPDIR)/syscall/syscall_wraps.ldcmd
```

Change:

```
LDFLAGS += -gc-sections
```

to:

```
LDFLAGS += -Wl,-gc-sections
```

Change:

```
$(LIBPATHS) "-(" $(LDLIBS) "-)" $(LDFLAGS) -Map="$(TOPDIR)$(DELIM)nuttx.map"
```

to:

```
$(LIBPATHS) "-(" $(LDLIBS) "-)" $(LDFLAGS) -Wl,-Map="$(TOPDIR)$(DELIM)nuttx.map"
```

Change:

```
NXFLATLDFLAGS1 = -r -d -warn-common
```

to:

```
NXFLATLDFLAGS1 = -r -Wl,-d -Wl,-warn-common
```

Change:

```
ifeq ($(CONFIG_CYGWIN_WINTOOL),y)
  LDFLAGS += -Map="${shell cygpath -w $(TOPDIR)/nuttx.map}" --cref
else
  LDFLAGS += -Map=$(TOPDIR)/nuttx.map --cref
endif
```

to:

```
ifeq ($(CONFIG_CYGWIN_WINTOOL),y)
  LDFLAGS += -Wl,-Map="${shell cygpath -w $(TOPDIR)/nuttx.map}" -Wl,--cref
else
  LDFLAGS += -Wl,-Map=$(TOPDIR)/nuttx.map -Wl,--cref
endif
```

Also, if you have assigned the LD variable, it would need to change as well:

Change:

```
LD = $(CROSSDEV)ld
```

to:

```
LD = $(CROSSDEV)gcc
```

#### References

* Git commit # 45672c269db13f59bdaa417e564837e8bbb6c8c1 in the NuttX main repository:
  - https://github.com/apache/incubator-nuttx/commit/45672c269db13f59bdaa417e564837e8bbb6c8c1
* PR-3836 in the NuttX main repository:
  - https://github.com/apache/incubator-nuttx/pull/3836
* Issues 3209 and 3826 in the NuttX issue tracker:
  - https://github.com/apache/incubator-nuttx/issues/3209
  - https://github.com/apache/incubator-nuttx/issues/3826
* Description of the change on Binutils mailing list:
  - https://sourceware.org/pipermail/binutils/2021-June/116826.html
* Description of -Wl,option in the GCC manual:
  - https://gcc.gnu.org/onlinedocs/gcc/Link-Options.html