Hardware System Abstraction (HAL)

Cryptoauthlib HAL Architecture

Cryptoauthlib has several intermediate conceptual layers

The highest layer of cryptoauthlib (outside of integration APIS) that may be used with an application is the atcab_ api functions. These are general purpose functions that present a simple and consistent crypto interface to the application regardless of the device being used.
calib_, talib_ APIs are the library functions behind atcab_ ones that generate the correct command packets and process the received responses. Device specific logic is handled by the library here
hal_ these functions perform the transmit/recieve of data for a given interface. These are split into sublayers
- The HAL layer is the first hal layer that presents the interface expected by the higher level library. When using a native driver and no further interpretation is required this layer is all that is required.
- The PHY layer if for hals that perform an interpretation or additional protocol logic. In this situation the HAL performs protocol interpretation while the phy performs the physical communication

The hal and phy layers have the same construction. A hal or phy must have the following functions and their signatures

ATCA_STATUS hal__init(ATCAIface iface, ATCAIfaceCfg *cfg);
ATCA_STATUS hal__post_init(ATCAIface iface);
ATCA_STATUS hal__send(ATCAIface iface, uint8_t address, uint8_t *txdata, int txlength);
ATCA_STATUS hal__receive(ATCAIface iface, uint8_t address, uint8_t *rxdata, uint16_t *rxlength);
ATCA_STATUS hal__control(ATCAIface iface, uint8_t option, void* param, size_t paramlen);
ATCA_STATUS hal__release(void *hal_data);

If the hal is a native driver no phy is required. See the tables below for which hal is required to be ported based on a configured interface

Device Interface	Physical Interface	HAL	PHY
i2c	i2c	hal_i2c
	gpio	hal_i2c_gpio	hal_gpio
spi	spi	hal_spi
swi	uart	hal_swi	hal_uart
	gpio	hal_swi_gpio	hal_gpio
any	uart	kit	hal_uart
	hid	kit	hal_hid
	any (user provided)	kit_bridge

Obtain library and configure using Harmony 3

Interface	Files	API	Notes
I2C	hal_i2c_harmony.c	plib.h	For all Harmony 3 based projects
SPI	hal_spi_harmony.c	plib.h
UART	hal_uart_harmony.c	plib.h

Obtain library and integration through Microchip Code Configurator

Use CMake to configure the library in Linux, Windows, and MacOS environments

OS	Interface	Files	API	Notes
Linux	I2C	hal_linux_i2c_userspace.c/h	i2c-dev
Linux	SPI	hal_linux_spi_userspace.c/h	spidev
Linux/Mac		hal_linux.c		For all Linux/Mac projects
Windows		hal_windows.c		For all Windows projects
All	kit-hid	hal_all_platforms_kit_hidapi.c/h	hidapi	Works for Windows, Linux, and Mac
freeRTOS		hal_freertos.c		freeRTOS common routines

Interface	Files	API	Notes
	hal_timer_start.c	START	Timer implementation
I2C	hal_i2c_start.c/h	START
SWI	swi_uart_start.c/h	START	SWI using UART

SAM Micros	Interface	Files	API	Notes
cortex-m0	I2C	hal_sam0_i2c_asf.c/h	ASF3	SAMD21, SAMB11, etc
cortex-m3/4/7	I2C	hal_sam_i2c_asf.c/h	ASF3	SAM4S, SAMG55, SAMV71, etc
all		hal_sam_timer_asf.c	ASF3	Common timer hal for all platforms

	Cryptoauthentication Device Library