123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268 |
- /**
- * Copyright (c) 2014 - 2020, Nordic Semiconductor ASA
- *
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without modification,
- * are permitted provided that the following conditions are met:
- *
- * 1. Redistributions of source code must retain the above copyright notice, this
- * list of conditions and the following disclaimer.
- *
- * 2. Redistributions in binary form, except as embedded into a Nordic
- * Semiconductor ASA integrated circuit in a product or a software update for
- * such product, must reproduce the above copyright notice, this list of
- * conditions and the following disclaimer in the documentation and/or other
- * materials provided with the distribution.
- *
- * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
- * contributors may be used to endorse or promote products derived from this
- * software without specific prior written permission.
- *
- * 4. This software, with or without modification, must only be used with a
- * Nordic Semiconductor ASA integrated circuit.
- *
- * 5. Any software provided in binary form under this license must not be reverse
- * engineered, decompiled, modified and/or disassembled.
- *
- * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
- * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
- * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
- * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
- * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- */
- /** @file
- *
- * @defgroup ser_hal_transport Serialization HAL Transport
- * @{
- * @ingroup ble_sdk_lib_serialization
- *
- * @brief HAL Transport layer for serialization.
- *
- * @details The @ref ser_hal_transport declares functions and typedefs used as API of the HAL
- * transport layer for serialization. This layer is fully hardware-independent.
- * Currently, the HAL transport layer is responsible for controlling the PHY layer and
- * memory management. In the future, more features might be added to it, such as CRC
- * or retransmission.
- *
- * \n \n
- * \image html ser_hal_transport_rx_state_machine.svg "RX state machine"
- * \n \n
- * \image html ser_hal_transport_tx_state_machine.svg "TX state machine"
- * \n
- */
- #ifndef SER_HAL_TRANSPORT_H__
- #define SER_HAL_TRANSPORT_H__
- #include <stdint.h>
- #ifdef __cplusplus
- extern "C" {
- #endif
- /**@brief Serialization HAL Transport layer event types. */
- typedef enum
- {
- SER_HAL_TRANSP_EVT_TX_PKT_SENT = 0, /**< An event indicating that TX packet has been
- transmitted. */
- SER_HAL_TRANSP_EVT_RX_PKT_RECEIVING, /**< An event indicating that RX packet is being
- scheduled to receive or to drop. */
- SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED, /**< An event indicating that RX packet is ready for
- read. */
- SER_HAL_TRANSP_EVT_RX_PKT_DROPPED, /**< An event indicating that RX packet was dropped
- because it was longer than available buffer. */
- SER_HAL_TRANSP_EVT_PHY_ERROR, /**< An event indicating error on PHY layer. */
- SER_HAL_TRANSP_EVT_TYPE_MAX /**< Enumeration upper bound. */
- } ser_hal_transport_evt_type_t;
- /**@brief Serialization PHY layer error types. */
- typedef enum
- {
- SER_HAL_TRANSP_PHY_ERROR_RX_OVERFLOW = 0, /**< An error indicating that more information has
- been transmitted than the PHY module could handle. */
- SER_HAL_TRANSP_PHY_ERROR_TX_OVERREAD, /**< An error indicating that the PHY module was forced to
- transmit more information than possessed. */
- SER_HAL_TRANSP_PHY_ERROR_HW_ERROR, /**< An error indicating a hardware error in the PHY
- module. */
- SER_HAL_TRANSP_PHY_ERROR_TYPE_MAX /**< Enumeration upper bound. */
- } ser_hal_transport_phy_error_type_t;
- /**@brief Struct containing parameters of event of type
- * @ref SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED.
- */
- typedef struct
- {
- uint8_t * p_buffer; /**< Pointer to a buffer containing a packet to read. */
- uint16_t num_of_bytes; /**< Length of a received packet in octets. */
- } ser_hal_transport_evt_rx_pkt_received_params_t;
- /**@brief Struct containing parameters of event of type @ref SER_HAL_TRANSP_EVT_PHY_ERROR. */
- typedef struct
- {
- ser_hal_transport_phy_error_type_t error_type; /**< Type of the PHY error. */
- uint32_t hw_error_code; /**< Hardware error code - specific for a microcontroller. Parameter
- is valid only for the PHY error of type
- @ref SER_HAL_TRANSP_PHY_ERROR_HW_ERROR. */
- } ser_hal_transport_evt_phy_error_params_t;
- /**@brief Struct containing events from the Serialization HAL Transport layer.
- *
- * @note Some events do not have parameters, then the whole information is contained in the evt_type.
- */
- typedef struct
- {
- ser_hal_transport_evt_type_t evt_type; /**< Type of event. */
- union /**< Union alternative identified by evt_type in the enclosing struct. */
- {
- ser_hal_transport_evt_rx_pkt_received_params_t rx_pkt_received; /**< Parameters of event of type @ref SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED. */
- ser_hal_transport_evt_phy_error_params_t phy_error; /**< Parameters of event of type @ref SER_HAL_TRANSP_EVT_PHY_ERROR. */
- } evt_params;
- } ser_hal_transport_evt_t;
- /**@brief Generic callback function type to be used by all Serialization HAL Transport layer
- * events.
- *
- * @param[in] event Serialization HAL Transport layer event.
- */
- typedef void (*ser_hal_transport_events_handler_t)(ser_hal_transport_evt_t event);
- /**@brief Function for opening and initializing the Serialization HAL Transport layer.
- *
- * @note The function opens the transport channel, initializes a PHY layer, and registers the callback
- * function to be used by all Serialization HAL Transport layer events.
- *
- * @warning If the function has been already called, the function @ref ser_hal_transport_close has
- * to be called before ser_hal_transport_open can be called again.
- *
- * @param[in] events_handler Generic callback function to be used by all Serialization HAL
- * Transport layer events.
- *
- * @retval NRF_SUCCESS Operation success.
- * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
- * @retval NRF_ERROR_INVALID_PARAM Operation failure. Hardware initialization parameters taken from
- * the configuration file are wrong.
- * @retval NRF_ERROR_INVALID_STATE Operation failure. The function has been already called. To call
- * it again the function @ref ser_hal_transport_close has to be
- * called first.
- * @retval NRF_ERROR_INTERNAL Operation failure. Internal error ocurred.
- */
- uint32_t ser_hal_transport_open(ser_hal_transport_events_handler_t events_handler);
- /**@brief Function for reseting ser_hal_transport. */
- void ser_hal_transport_reset(void);
- /**@brief Function for closing a transport channel.
- *
- * @note The function disables the hardware, resets internal module states, and unregisters the events
- * callback function. Can be called multiple times, also for a channel that is not opened.
- */
- void ser_hal_transport_close(void);
- /**@brief Function for freeing memory allocated for an RX packet.
- *
- * @note The function should be called as a response to an event of type
- * @ref SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED when the received data has beed processed. The function
- * frees the RX memory pointed by p_buffer. The memory, immediately or at a later time, is
- * reused by the underlying transport layer.
- *
- * @param[in] p_buffer A pointer to the beginning of the buffer that has been processed (has to be
- * the same address as provided in the event of type
- * @ref SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED).
- *
- * @retval NRF_SUCCESS Operation success.
- * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
- * @retval NRF_ERROR_INVALID_ADDR Operation failure. Not a valid pointer (provided address is not
- * the starting address of a buffer managed by HAL Transport layer).
- * @retval NRF_ERROR_INVALID_STATE Operation failure. The function should be called as a response
- * to an event of type @ref SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED.
- * @retval NRF_ERROR_INTERNAL Operation failure. Internal error ocurred.
- */
- uint32_t ser_hal_transport_rx_pkt_free(uint8_t * p_buffer);
- /**@brief Function for allocating memory for a TX packet.
- *
- * @param[out] pp_memory A pointer to pointer to which an address of the beginning of the
- * allocated buffer is written.
- * @param[out] p_num_of_bytes A pointer to a variable to which size in octets of the allocated
- * buffer is written.
- *
- * @retval NRF_SUCCESS Operation success. Memory was allocated.
- * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
- * @retval NRF_ERROR_NO_MEM Operation failure. No memory available.
- * @retval NRF_ERROR_INVALID_STATE Operation failure. The function was called before calling
- * @ref ser_hal_transport_open function.
- */
- uint32_t ser_hal_transport_tx_pkt_alloc(uint8_t ** pp_memory, uint16_t * p_num_of_bytes);
- /**@brief Function for transmitting a packet.
- *
- * @note The function adds a packet pointed by the p_buffer parameter to a transmission queue. A buffer
- * provided to this function must be allocated by the @ref ser_hal_transport_tx_pkt_alloc function.
- *
- * @warning Completion of this method does not guarantee that actual peripheral transmission will be completed.
- *
- * @param[in] p_buffer Pointer to the buffer to transmit.
- * @param[in] num_of_bytes Number of octets to transmit. Must be more than 0.
- *
- * @retval NRF_SUCCESS Operation success. Packet was added to the transmission queue.
- * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
- * @retval NRF_ERROR_INVALID_PARAM Operation failure. num_of_bytes is equal to 0.
- * @retval NRF_ERROR_INVALID_ADDR Operation failure. Not a valid pointer (provided address is not
- * the starting address of a buffer managed by HAL Transport layer).
- * @retval NRF_ERROR_DATA_SIZE Operation failure. Packet size exceeds limit.
- * @retval NRF_ERROR_BUSY Operation failure. Transmission queue is full so packet was not
- * added to the transmission queue.
- * @retval NRF_ERROR_INVALID_STATE Operation failure. Transmittion channel was not opened by
- * @ref ser_hal_transport_open function or provided buffer was not
- * allocated by @ref ser_hal_transport_tx_pkt_alloc function.
- * @retval NRF_ERROR_INTERNAL Operation failure. Internal error ocurred.
- */
- uint32_t ser_hal_transport_tx_pkt_send(const uint8_t * p_buffer, uint16_t num_of_bytes);
- /**@brief Function for freeing memory allocated for a TX packet.
- *
- * @note The function frees the TX memory pointed by p_buffer. Freeing a TX buffer is possible only if
- * the buffer was allocated by @ref ser_hal_transport_tx_pkt_alloc function and transmittion
- * is not in progress. When transmittion has finished, this function is automatically called by
- * the Serialization HAL Transport layer, so the only case when this function should be used
- * from outside is when a TX buffer was allocated but a transmittion has not been started
- * (@ref ser_hal_transport_tx_pkt_send function has not been called).
- *
- * @param[in] p_buffer Pointer to the beginning of a buffer that has been allocated by
- * @ref ser_hal_transport_tx_pkt_alloc function.
- *
- * @retval NRF_SUCCESS Operation success. Memory was freed.
- * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
- * @retval NRF_ERROR_INVALID_ADDR Operation failure. Not a valid pointer (provided address is not
- * the starting address of a buffer managed by HAL Transport layer).
- * @retval NRF_ERROR_INVALID_STATE Operation failure. Freeing a TX buffer is possible only if the
- * buffer was allocated by @ref ser_hal_transport_tx_pkt_alloc
- * function and transmittion is not in progress.
- */
- uint32_t ser_hal_transport_tx_pkt_free(uint8_t * p_buffer);
- #ifdef __cplusplus
- }
- #endif
- #endif /* SER_HAL_TRANSPORT_H__ */
- /** @} */
|