Skip to content

Latest commit

 

History

History
59 lines (49 loc) · 3.87 KB

readme.md

File metadata and controls

59 lines (49 loc) · 3.87 KB
Raw

This folder contains the sources to bootstrap development of a new HAL implementation.

Bootstrapping a new HAL:

  • test build an empty HAL: make PLATFORM_ID=60000 this creates empty elf files for the bootloader and main. (They are empty because the linker scripts are empty, so no sections are output.)
  • get a new Platform ID from Particle (or assign the next free one yourself temporarily until one is assigned to you). Platform IDs are listed in build/platform-id.mk
  • duplicate all the parts in platform-id.mk referring to newhal and rename to your product
  • duplicate this directory (hal/src/newhal/), and rename to match PLATFORM_NAME as defined for your product (in platform-id.mk)
  • duplicate platform/MCU/newhal-mcu to a new folder and rename to match the PLATFORM_MCU value for your product (in product-id.mk)
  • duplicate build/arm/linker/linker_newhalcpu.ld and rename, substituting newhalcpu for the value of MCU_DEVICE for your product.
  • duplicate build/arm/startup/linker_newhalcpu.S and rename, substituting newhalcpu for the value of MCU_DEVICE for your product.
  • create a new symbolic reference for your new platform in firmware/platform/shared/platforms.h that uses the same PLATFORM_ID you created earlier (e.g. #define PLATFORM_BORON 13).
  • add your new symbolic reference to platform_config.h to keep this from throwing an error, optionally add it in the appropriate places and configure all of the pin/port/interrupt mapping.
  • test build - make clean all -s PLATFORM_ID=<your platform id> should now build the empty bootloader and firmware.

Development typically starts off without a bootloader, focusing initially on building the firmware by porting the HAL to your target device.

Your hal implementation directory is hal/src/<yourproduct>.

These are the outline steps to implement a new HAL:

  • add memory regions, linker sections (interrupt vector table, .text, .rodata, .data, .bss, etc..), entry function etc. to the linker.ld script located here hal/src/<yourproduct>. Alternatively you may rename this file, and point to it from the INCLUDE.mk file located in the same place. Make sure to also include the directory hal/src/<yourproduct> in the commented out LDFLAGS += -L/some/directory in INCLUDE.mk. If you are unfamiliar with the terminology in a linker script, this is a good reference on the linker command language.
  • Do not move on until: 1) all ASSERT commands at the end of the linker script pass. 2) functions may be missing from the hal/src/template files, which will generate undefined references until you add them in their respective template files. 3) the main build target completes and starts to have a filesize as follows:
mv ../build/target/main/platform-13/main.bin.pre_crc ../build/target/main/platform-13/main.bin
   text	   data	    bss	    dec	    hex	filename
  13096	    224	   2156	  15476	   3c74	../build/target/main/platform-13/main.elf
  • copy individual files from hal/src/template to your hal implementation folder. It's ok to rename the file from .c to .cpp and vice-versa.
  • implement the function bodies in the chosen file

Suggested porting order to get a device connected to the cloud:

  • core_hal (initialization, sleep modes)
  • deviceid_hal (the unique ID send to the cloud)
  • usb_hal (for Serial output)
  • timer_hal
  • delay_hal
  • wlan_hal (smartconfig is optional)
  • inet_hal
  • socket_hal (server sockets are not used to communicate with the cloud)
  • ota_flash_hal (to support OTA updates)

The remainder of the files are for dealing with peripherals - from the perspective of the core system, these are all optional and are only used from user code:

  • adc_hal
  • dac_hal
  • eeprom_hal
  • gpio_hal
  • i2c_hal
  • interrupts_hal
  • pinmap_hal
  • pwm_hal
  • rng_hal
  • rtc_hal
  • servo_hal
  • spi_hal
  • tone_hal
  • usart_hal