API documentation

BSD Library Management

group bsd

Application Interface offered for management of BSD Library.

Functions

void bsd_init(void)

Method to initialize BSD library.

This method shall be called before using any of the other methods of the application. In case the initialization fails, the call results in a hard fault.

This method shall be called once. Calling this method again with a shutdown results in undefined behavior.

Initializing the library results in reserving resources defined in bsd_platform.h on the system. The application shall not use any of the resources identified in bsd_platform.h.

Note
This API is designed to provide flexibility of being called from startup scripts.

void bsd_shutdown(void)

Method to gracefully shutdown the BSD library.

This method used to shutdown the library. Resources reserved by the system may be reused once the library is gracefully shutdown.

void bsd_recoverable_error_handler(uint32_t error)

Handler for recoverable BSD library errors.

Note
It can be overwritten by the application. The default will hard fault.
Parameters
  • error: Indicates the error that occurred.

void bsd_irrecoverable_error_handler(uint32_t error)

Handler for irrecoverable BSD library errors.

Note
It can be overwritten by the application. The default will hard fault.
Parameters
  • error: Indicates the error that occurred.

Limits of the BSD library

group bsd_limits

Upper and lower bound limits of BSD library.

This module provides:

  1. A common entry point for limits specific system initializations.
  2. Limits specific parameters:
    1. Maximum number of concurrent sockets in the system.
    2. Maximum number of concurrent secure sockets in the system.
    3. Maximum number AT sockets and subscriptions for AT events in the system.
    4. ..

Defines

BSD_MAX_IP_SOCKET_COUNT

Maximum number of sockets of IP sockets.

BSD_MAX_AT_SOCKET_COUNT

Maximum AT sockets.

BSD_MAX_SOCKET_COUNT

Maximum number of sockets available in the system.

Maximum number of sockets that can be opened using the BSD library. The socket may be of any type. IPv4, IPV6, AT etc. This upper bound applies irrespective of which type of socket was in use.

In short, this value is, MAX(BSD_MAX_IP_SOCKET_COUNT, BSD_MAX_AT_SOCKET_COUNT).

BSD_AT_MAX_CMD_SIZE

Maximum AT Command Size in bytes.

BSD_MAX_PDN_COUNT

Maximum number of PDN connections that can be created.

Maximum number of concurrent PDN connections that can be created and managed on the system. This number include any default PDNs.

BSD Platform

group bsd_platform_ipc

Platform Initialization and system resource usage.

This module provides:

  1. A common entry point for platform specific system initializations.
  2. Initialization of modules, in right order and with platform specific tuning.
  3. Any system level configurations. These configurations include:
    1. Interrupts and their priorities.
    2. Any reserved memory.
    3. Any other reserved resources in the system for the purpose.

group bsd_version

BSD Library version number.

Defines

BSD_VERSION_MAJOR_NUMBER

Major version number.

BSD_VERSION_MINOR_NUMBER

Minor version number.

group bsd_reserved_memory

Memory reserved by the BSD library for communication with the application and the network layer.

Defines

BSD_RESERVED_MEMORY_ADDRESS

Memory start address reserved by the BSD library.

BSD_RESERVED_MEMORY_SIZE

Memory size reserved by the BSD library. This value has to match with the application RAM start address defined in the linker script.

group BSD_reserved_interrupts

Interrupts and priorities reserved by the BSD library for communication with the application and the network layer.

Defines

BSD_NETWORK_IRQ

Interrupt used for communication with the network layer.

BSD_NETWORK_IRQ_PRIORITY

Interrupt priority used on interrupt for communication with the network layer.

BSD_APPLICATION_IRQ

Interrupt used for communication with the application layer.

BSD_APPLICATION_IRQ_HANDLER

Interrupt handler used for communication with the application layer.

BSD_APPLICATION_IRQ_PRIORITY

Interrupt priority used on interrupt for communication with the application layer.

RPC_MAX_CLIENTS

Maximum number of client that can be registered with RPC.

RPC_MAX_TRANSPORT_INSTANCES

Maximum transport instances supported for RPC.

nRF91 Inbuilt Key Management

group nrf_inbuilt_key

Functions

int nrf_inbuilt_key_write(nrf_sec_tag_t sec_tag, nrf_key_mgnt_cred_type_t cred_type, uint8_t *p_buffer, uint16_t buffer_len)

Provision new or update credential in persistent storage.

This function will store the credential referenced to be stored persistently. The credential can later be referenced for use or managed by nrf_inbuilt_key module by using the application defined sec_tag.

Parameters
  • sec_tag: Application defined tag for this credential to be referred to in setting up a BSD Secure Socket or to manage the credential using nrf_key_mgmt module to read/delete/search the key.
  • cred_type: Type of credential being created and stored for later use.
  • p_buffer: Buffer containing the credential data.
  • buffer_len: Length of the buffer holding the credential data.
Return Value
  • 0: If create operation was successful.
  • NRF_EIO: If operation was not successful due to internal error or uninitialized module.
  • NRF_ENOBUFS: If the operation could not be performed because it could not allocate enough intermediate buffers to perform the operation.
  • NRF_ENOENT: If the sec_tag indicated cannot be written.
  • NRF_ENOMEM: If there was not memory enough to store the credential data.
  • NRF_EPERM: If the application did not have permission to do the operation.
  • NRF_EACCES: If the operation could not be performed while modem is in active state.
  • NRF_EINVAL: If one or more of the provided parameters are not valid.

int nrf_inbuilt_key_read(nrf_sec_tag_t sec_tag, nrf_key_mgnt_cred_type_t cred_type, uint8_t *p_buffer, uint16_t *p_buffer_len)

Read back a credential from persistent storage.

This function will read the credential from persistent memory referenced by a sec_tag.

Parameters
  • sec_tag: Application defined tag for this credential to read.
  • cred_type: Type of credential being read.
  • p_buffer: Output buffer containing where to write the read credential data.
  • p_buffer_len: Length of the output buffer as input, and length used as output parameter.
Return Value
  • 0: If read operation was successful.
  • NRF_EIO: If operation was not successful due to internal error or uninitialized module.
  • NRF_ENOBUFS: If the operation could not be performed because it could not allocate enough intermediate buffers to perform the operation.
  • NRF_ENOENT: If there was no credential associated with the sec_tag and cred_type.
  • NRF_EPERM: If the application did not have permission to do the operation.
  • NRF_EACCES: If the operation could not be performed while modem is in active state.
  • NRF_EINVAL: If provided buffer is to small for result data. If failing with this error, the size needed is provided as output parameter by reference in the output p_buffer_len output parameter.

int nrf_inbuilt_key_delete(nrf_sec_tag_t sec_tag, nrf_key_mgnt_cred_type_t cred_type)

Delete a credential from persistent storage.

This function deletes a stored credential from the persistent storage.

Parameters
  • sec_tag: Application defined tag to delete.
  • cred_type: Type of credential being deleted.
Return Value
  • 0: If delete operation was successful.
  • NRF_EIO: If operation was not successful due to internal errors or uninitialized module.
  • NRF_ENOBUFS: If the operation could not be performed because it could not allocate enough intermediate buffers to perform the operation.
  • NRF_ENOENT: If there was no credential associated with the sec_tag and cred_type.
  • NRF_EPERM: If the application did not have permission to do the operation.
  • NRF_EACCES: If the operation could not be performed while modem is in active state.

int nrf_inbuilt_key_permission_set(nrf_sec_tag_t sec_tag, nrf_key_mgnt_cred_type_t cred_type, uint8_t perm_flags)

Set permission on a credential in persistent storage.

This function will set permissions on the credential referenced in persistently storage by a sec_tag and credential type.

Parameters
  • sec_tag: Application defined tag for this credential apply the permissions to.
  • cred_type: Type of credential to apply the permissions to.
  • perm_flags: Permission flags. Not yet implemented/supported.
Return Value
  • 0: If create operation was successful.
  • NRF_EIO: If operation was not successful due to internal errors or uninitialized module.
  • NRF_ENOBUFS: If the operation could not be performed because it could not allocate enough intermediate buffers to perform the operation.
  • NRF_ENOENT: If there was no credential associated with the sec_tag and cred_type.
  • NRF_EPERM: If the application did not have permission to do the operation.
  • NRF_EACCES: If the operation could not be performed while modem is in active state.

int nrf_inbuilt_key_exists(nrf_sec_tag_t sec_tag, nrf_key_mgnt_cred_type_t cred_type, bool *p_exists, uint8_t *p_perm_flags)

Check if credential exists in persistent storage.

This function do a check whether the credential exists in the persistent storage.

Parameters
  • sec_tag: Application defined tag for search for.
  • cred_type: Type of credential being searched read.
  • p_exists: Value by reference output parameter telling the existence of the credential. Only valid if operation was successful.
  • p_perm_flags: Value by reference output parameter telling the permission flags of the credential. Only valid if operation was successful and
  • p_exists: is true. Not yet implemented/supported.
Return Value
  • 0: If delete operation was successful.
  • NRF_EIO: If operation was not successful due to internal errors or uninitialized module.
  • NRF_ENOBUFS: If the operation could not be performed because it could not allocate enough intermediate buffers to perform the operation.
  • NRF_ENOENT: If there was no credential associated with the sec_tag and cred_type.
  • NRF_EPERM: If the application did not have permission to do the operation.
  • NRF_EACCES: If the operation could not be performed while modem is in active state.

nRF91 Key Management

group nrf_key_mgmt

Enums

enum nrf_key_mgnt_cred_type_t

Enumeration values for credentials types available in the key management module.

Values:

NRF_KEY_MGMT_CRED_TYPE_CA_CHAIN
NRF_KEY_MGMT_CRED_TYPE_PUBLIC_CERT
NRF_KEY_MGMT_CRED_TYPE_PRIVATE_CERT
NRF_KEY_MGMT_CRED_TYPE_PSK
NRF_KEY_MGMT_CRED_TYPE_IDENTITY

nRF BSD Socket interface

group nrf_socket

Nordic socket interface.

This module provides the socket interface for writing nRF applications. The API is designed to be compatible with the POSIX/BSD socket interface for the purpose of making porting easy.

Unnamed Group

int nrf_poll(struct nrf_pollfd *p_fds, uint32_t nfds, int timeout)

Method to poll for events on one or more sockets.

Parameters
  • An: array of sockets, and respective for each socket that the caller polls for. The occurred events per socket is returned in the requested field of struct nrf_pollfd structure. Shall not be NULL.
  • Positive: number of sockets being polled for events. Shall not be more than BSD_MAX_SOCKET_COUNT.
  • Timeout: in milliseconds. The methods waits for this time period for the events to occur on the sockets.
Return Value
  • A: positive number less than or equal to nfds indicating sockets on which events occurred. 0 indicates the timed out occurred and no file descriptors were ready. -1 on error, and errno indicates the reason for failure.

Defines

NRF_HTONS(val)

Host to network byte-orders on half word.

NRF_HTONL(val)

Host to network byte-orders on full word.

NRF_NTOHS(val)

Network to host byte-orders on half word.

NRF_NTOHL(val)

Network to host byte-orders on full word.

nrf_htons(x)

Convert byte order from host to network (short).

nrf_htonl(x)

Convert byte order from host to network (long).

nrf_ntohs(x)

Convert byte order from network to host (short).

nrf_ntohl(x)

Convert byte order from network to host (long).

Typedefs

typedef int32_t ssize_t
typedef uint32_t nrf_socklen_t

Socket module size type.

typedef uint16_t nrf_in_port_t

Socket port type.

typedef int nrf_socket_family_t

Socket families.

For a list of valid values, refer to Values for nrf_socket_family_t.

typedef nrf_socket_family_t nrf_sa_family_t
typedef uint32_t nrf_in_addr_t

IPv4 address.

Functions

int nrf_socket(int family, int type, int protocol)

Function for creating a socket.

API to create a socket that can be used for network communication independently of lower protocol layers.

Return
A non-negative socket descriptor on success, or -1 on error.
Parameters
  • family: The protocol family of the network protocol to use.
  • type: The protocol type to use for this socket.
  • protocol: The transport protocol to use for this socket.

int nrf_close(int sock)

Function for closing a socket and freeing any resources held by it.

If the socket is already closed, this function does nothing.

Return
0 on success, or -1 on error.
Parameters
  • sock: The socket to close.

int nrf_fcntl(int fd, int cmd, int flags)

Function for controlling file descriptor options.

Set or get file descriptor options or flags. For a list of supported commands, refer to fcntl commands. For a list of supported flags, refer to fcntl flags.

Parameters
  • fd: The descriptor to set options on.
  • cmd: The command class for options.
  • flags: The flags to set.

int nrf_connect(int sock, const void *p_servaddr, nrf_socklen_t addrlen)

Function for connecting to an endpoint with a given address.

The socket handle must be a valid handle that has not yet been connected. Running connect on a connected handle will return an error.

Return
0 on success, or -1 on error.
Parameters
  • sock: The socket to use for connection.
  • p_servaddr: The address of the server to connect to.
  • addrlen: The size of the p_servaddr argument.

ssize_t nrf_send(int sock, const void *p_buff, size_t nbytes, int flags)

Function for sending data through a socket.

By default, this function will block unless the NRF_O_NONBLOCK socket option has been set, OR NRF_MSG_DONTWAIT is passed as a flag. In that case, the method will return immediately.

Return
The number of bytes that were sent on success, or -1 on error.
Parameters
  • sock: The socket to write data to.
  • p_buff: Buffer containing the data to send.
  • nbytes: Size of data contained on p_buff.
  • flags: Flags to control send behavior.

ssize_t nrf_sendto(int sock, const void *p_buff, size_t nbytes, int flags, const void *p_servaddr, nrf_socklen_t addrlen)

Function for sending datagram through a socket.

By default, this function will block if the lower layers are not able to process the packet, unless the NRF_O_NONBLOCK socket option has been set, OR NRF_MSG_DONTWAIT is passed as a flag. In that case, the method will return immediately.

Return
The number of bytes that were sent on success, or -1 on error.
Parameters
  • sock: The socket to write data to.
  • p_buff: Buffer containing the data to send.
  • nbytes: Size of data contained in p_buff.
  • flags: Flags to control send behavior.
  • p_servaddr: The address of the server to send to.
  • addrlen: The size of the p_servaddr argument.

ssize_t nrf_write(int sock, const void *p_buff, size_t nbytes)

Function for writing data to a socket. See nrf_send() for details.

Return
The number of bytes that were sent on success, or -1 on error.
Parameters
  • sock: The socket to write data to.
  • p_buff: Buffer containing the data to send.
  • nbytes: Size of data contained in p_buff.

ssize_t nrf_recv(int sock, void *p_buff, size_t nbytes, int flags)

Function for receiving data on a socket.

API for receiving data from a socket. By default, this function will block, unless the NRF_O_NONBLOCK socket option has been set, or NRF_MSG_DONTWAIT is passed as a flag.

Return
The number of bytes that were read, or -1 on error.
Parameters
  • sock: The socket to receive data from.
  • p_buff: Buffer to hold the data to be read.
  • nbytes: Number of bytes to read. Should not be larger than the size of p_buff.
  • flags: Flags to control receive behavior.

ssize_t nrf_recvfrom(int sock, void *p_buff, size_t nbytes, int flags, void *p_cliaddr, nrf_socklen_t *p_addrlen)

Function for receiving datagram on a socket.

API for receiving data from a socket. By default, this function will block, unless the NRF_O_NONBLOCK socket option has been set, or NRF_MSG_DONTWAIT is passed as a flag.

Return
The number of bytes that were read, or -1 on error.
Parameters
  • sock: The socket to receive data from.
  • p_buff: Buffer to hold the data to be read.
  • nbytes: Number of bytes to read. Should not be larger than the size of p_buff.
  • flags: Flags to control receive behavior.
  • p_cliaddr: Socket address that will be set to the client’s address.
  • p_addrlen: The size of the p_cliaddr passed. Might be modified by the function.

ssize_t nrf_read(int sock, void *p_buff, size_t nbytes)

Function for reading data from a socket. See nrf_recv() for details.

Return
The number of bytes that were read, or -1 on error.
Parameters
  • sock: The socket to receive data from.
  • p_buff: Buffer to hold the data to be read.
  • nbytes: Number of bytes to read. Should not be larger than the size of p_buff.

int nrf_select(int nfds, nrf_fd_set *p_readset, nrf_fd_set *p_writeset, nrf_fd_set *p_exceptset, const struct nrf_timeval *p_timeout)

Function for waiting for read, write, or exception events on a socket.

Wait for a set of socket descriptors to be ready for reading, writing, or having exceptions. The set of socket descriptors is configured before calling this function. This function will block until any of the descriptors in the set has any of the required events. This function is mostly useful when using NRF_O_NONBLOCK or NRF_MSG_DONTWAIT options to enable asynchronous operation.

Return
The number of ready descriptors contained in the descriptor sets on success, or -1 on error.
Parameters
  • nfds: The highest socket descriptor value contained in the sets.
  • p_readset: The set of descriptors for which to wait for read events. Set to NULL if not used.
  • p_writeset: The set of descriptors for which to wait for write events. Set to NULL if not used.
  • p_exceptset: The set of descriptors for which to wait for exception events. Set to NULL if not used.
  • p_timeout: The timeout to use for select call. Set to NULL if waiting forever.

int nrf_setsockopt(int sock, int level, int optname, const void *p_optval, nrf_socklen_t optlen)

Function for setting socket options for a given socket.

The options are grouped by level, and the option value should be the expected for the given option, and the lifetime must be longer than that of the socket.

Return
0 on success, or -1 on error.
Parameters
  • sock: The socket for which to set the option.
  • level: The level or group to which the option belongs.
  • optname: The name of the socket option.
  • p_optval: The value to be stored for this option.
  • optlen: The size of p_optval.

int nrf_getsockopt(int sock, int level, int optname, void *p_optval, nrf_socklen_t *p_optlen)

Function for getting socket options for a given socket.

The options are grouped by level, and the option value is the value described by the option name.

Return
0 on success, or -1 on error.
Parameters
  • sock: The socket for which to set the option.
  • level: The level or group to which the option belongs.
  • optname: The name of the socket option.
  • p_optval: Pointer to the storage for the option value.
  • p_optlen: The size of p_optval. Can be modified to the actual size of p_optval.

int nrf_bind(int sock, const void *p_myaddr, nrf_socklen_t addrlen)

Function for binding a socket to an address and port.

The provided address must be supported by the socket protocol family.

Return
0 on success, or -1 on error.
Parameters
  • sock: The socket descriptor to bind.
  • p_myaddr: The address to bind this socket to.
  • addrlen: The size of p_myaddr.

int nrf_listen(int sock, int backlog)

Function to put the socket in listening mode for incoming connections.

Once a socket is marked to be in the listening state, it remains a listening socket until closed. It is important to consider the backlog parameter, as it will affect how much memory your application will use in the worst case.

Return
0 on success, or -1 on error.
Parameters
  • sock: The socket descriptor on which to set the listening options.
  • backlog: The max length of the queue of pending connections. A value of 0 means infinite.

int nrf_accept(int sock, void *p_cliaddr, nrf_socklen_t *p_addrlen)

Function for waiting for the next client to connect.

This function will block if there are no clients attempting to connect.

Return
A non-negative client descriptor on success, or -1 on error.
Parameters
  • sock: The socket descriptor to use for waiting on client connections.
  • p_cliaddr: Socket address that will be set to the client’s address.
  • p_addrlen: The size of the p_cliaddr passed. Might be modified by the function.

int nrf_inet_pton(int family, const char *p_src, void *p_dst)

Function for converting a human-readable IP address to a form usable by the socket API.

This function will convert a string form of addresses and encode it into a byte array.

Return
1 on success, 0 if p_src does not contain a valid address, -1 if family is not a valid address family.
Parameters
  • family: Address family. Only NRF_AF_INET supported.
  • p_src: Null-terminated string containing the address to convert.
  • p_dst: Pointer to a struct in6_addr where the address will be stored.

int nrf_getaddrinfo(const char *p_node, const char *p_service, const struct nrf_addrinfo *p_hints, struct nrf_addrinfo **pp_res)

Function to resolve the host name into IPv4 and/or IPv6 addresses.

Note
The memory pointed to by pp_res must be freed using nrf_freeaddrinfo when the address is no longer needed or before calling nrf_getaddrinfo again.
Return
0 if the procedure succeeds, else, an errno indicating the reason for failure.
Parameters
  • p_node: Host name to resolve.
  • p_service: Service to resolve.
  • p_hints: Any hints to be used for the resolution.
  • pp_res: Pointer to the linked list of resolved addresses if the procedure was successful.

void nrf_freeaddrinfo(struct nrf_addrinfo *p_res)

Function for freeing the memory allocated for the result of nrf_getaddrinfo.

When the linked list of resolved addresses created by getaddrinfo is no longer needed, call this function to free the allocated memory.

Parameters
  • p_res: Pointer to the memory to be freed.

Variables

const struct nrf_in6_addr nrf_in6addr_any

Global IPv6 any-address.

const struct nrf_in_addr nrf_inaddr_any

Global IPv4 any-address.

struct nrf_timeval
#include <nrf_socket.h>

Structure specifying time interval.

Public Members

uint32_t tv_sec

Time interval seconds.

uint32_t tv_usec

Time interval microseconds.

struct nrf_sockaddr
#include <nrf_socket.h>

Generic socket address.

Only provided for API compatibility.

struct nrf_in6_addr
#include <nrf_socket.h>

IPv6 address.

struct nrf_in_addr
#include <nrf_socket.h>

IPv4 address structure.

struct nrf_sockaddr_in6
#include <nrf_socket.h>

Address record for IPv6 addresses.

Contains the address and port of the host, as well as other socket options. All fields in this structure are compatible with the POSIX variant for API compatibility.

Public Members

uint8_t sin6_len

Length of this data structure.

nrf_sa_family_t sin6_family

Socket family.

nrf_in_port_t sin6_port

Port, in network byte order.

uint32_t sin6_flowinfo

IPv6 flow info parameters. Not used.

struct nrf_in6_addr sin6_addr

IPv6 address.

uint32_t sin6_scope_id

IPv6 scope ID. Not used.

struct nrf_sockaddr_in
#include <nrf_socket.h>

Address record for IPv4 addresses.

Contains the address and port of the host. All fields in this structure are compatible with the POSIX variant for API compatibility.

Public Members

uint8_t sin_len

Length of this data structure.

nrf_sa_family_t sin_family

Socket family.

nrf_in_port_t sin_port

Port, in network byte order.

struct nrf_in_addr sin_addr

IPv4 address.

Integer values for errno

group nrf_errno

OS specific definitions

group bsd_os

Functions

void bsd_os_init(void)
int32_t bsd_os_timedwait(uint32_t context, int32_t *p_timeout)
void bsd_os_errno_set(int errno_val)
void bsd_os_application_irq_clear(void)
void bsd_os_application_irq_set(void)
void bsd_os_trace_irq_set(void)
void bsd_os_trace_irq_clear(void)
int32_t bsd_os_trace_put(const uint8_t *const p_buffer, uint32_t buf_len)
void bsd_os_application_irq_handler(void)
void bsd_os_trace_irq_handler(void)