/**
 * \file pros/apix.h
 *
 * PROS Extended API header
 *
 * Contains additional declarations for use by advaned users of PROS. These
 * functions do not typically have as much error handling or require deeper
 * knowledge of real time operating systems.
 *
 * Visit https://pros.cs.purdue.edu/v5/extended/api.html to learn more.
 *
 * This file should not be modified by users, since it gets replaced whenever
 * a kernel upgrade occurs.
 *
 * \copyright Copyright (c) 2017-2023, Purdue University ACM SIGBots.
 * All rights reserved.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 */

#ifndef _PROS_API_EXTENDED_H_
#define _PROS_API_EXTENDED_H_

#include "api.h"
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wall"
#include "display/lvgl.h"
#pragma GCC diagnostic pop
#include "pros/serial.h"

#ifdef __cplusplus
#include "pros/serial.hpp"
namespace pros::c {
extern "C" {
#endif

/******************************************************************************/
/**                             RTOS FACILITIES                              **/
/**                                                                          **/
/**                                                                          **/
/**See https://pros.cs.purdue.edu/v5/extended/multitasking.html to learn more**/
/******************************************************************************/

typedef void* queue_t;
typedef void* sem_t;

/**
 * Unblocks a task in the Blocked state (e.g. waiting for a delay, on a
 * semaphore, etc.).
 *
 * See https://pros.cs.purdue.edu/v5/extended/multitasking.html#abort_delay for
 * details.
 */
bool task_abort_delay(task_t task);

/**
 * Notify a task when a target task is being deleted.
 *
 * This function will configure the PROS kernel to call
 * task_notify_ext(task_to_notify, value, action, NULL) when target_task is
 * deleted.
 *
 *
 * \param target_task
 *				The task being watched for deletion
 * \param task_to_notify
 *        The task to notify when target_task is deleted
 * \param value
 *				The value to supply to task_notify_ext
 * \param notify_action
 * 				The action to supply to task_notify_ext
 */
void task_notify_when_deleting(task_t target_task, task_t task_to_notify, uint32_t value,
                               notify_action_e_t notify_action);

/**
 * Creates a recursive mutex which can be locked recursively by the owner.
 *
 * See
 * https://pros.cs.purdue.edu/v5/extended/multitasking.html#recursive_mutexes
 * for details.
 *
 * \return A newly created recursive mutex.
 */
mutex_t mutex_recursive_create(void);

/**
 * Takes a recursive mutex.
 *
 * See
 * https://pros.cs.purdue.edu/v5/extended/multitasking.html#recursive_mutexes
 * for details.
 *
 * \param mutex
 *        A mutex handle created by mutex_recursive_create
 * \param wait_time
 *        Amount of time to wait before timing out
 *
 * \return 1 if the mutex was obtained, 0 otherwise
 */
bool mutex_recursive_take(mutex_t mutex, uint32_t timeout);

/**
 * Gives a recursive mutex.
 *
 * See
 * https://pros.cs.purdue.edu/v5/extended/multitasking.html#recursive_mutexes
 * for details.
 *
 * \param mutex
 *        A mutex handle created by mutex_recursive_create
 *
 * \return 1 if the mutex was obtained, 0 otherwise
 */
bool mutex_recursive_give(mutex_t mutex);

/**
 * Returns a handle to the current owner of a mutex.
 *
 * See https://pros.cs.purdue.edu/v5/extended/multitasking.html#extra for
 * details.
 *
 * \param mutex
 *        A mutex handle
 *
 * \return A handle to the current task that owns the mutex, or NULL if the
 * mutex isn't owned.
 */
task_t mutex_get_owner(mutex_t mutex);

/**
 * Creates a counting sempahore.
 *
 * See https://pros.cs.purdue.edu/v5/tutorials/multitasking.html#semaphores for
 *details.
 *
 * \param max_count
 *        The maximum count value that can be reached.
 * \param init_count
 *        The initial count value assigned to the new semaphore.
 *
 * \return A newly created semaphore. If an error occurred, NULL will be
 * returned and errno can be checked for hints as to why sem_create failed.
 */
sem_t sem_create(uint32_t max_count, uint32_t init_count);

/**
 * Deletes a semaphore (or binary semaphore)
 *
 * See https://pros.cs.purdue.edu/v5/extended/multitasking.html#semaphores for
 * details.
 *
 * \param sem
 * 			  Semaphore to delete
 */
void sem_delete(sem_t sem);

/**
 * Creates a binary semaphore.
 *
 * See
 * https://pros.cs.purdue.edu/v5/extended/multitasking#.htmlbinary_semaphores
 * for details.
 *
 * \return A newly created semaphore.
 */
sem_t sem_binary_create(void);

/**
 * Waits for the semaphore's value to be greater than 0. If the value is already
 * greater than 0, this function immediately returns.
 *
 * See https://pros.cs.purdue.edu/v5/tutorials/multitasking.html#semaphores for
 * details.
 *
 * \param sem
 *        Semaphore to wait on
 * \param timeout
 *        Time to wait before the semaphore's becomes available. A timeout of 0
 *        can be used to poll the sempahore. TIMEOUT_MAX can be used to block
 *        indefinitely.
 *
 * \return True if the semaphore was successfully take, false otherwise. If
 * false is returned, then errno is set with a hint about why the sempahore
 * couldn't be taken.
 */
bool sem_wait(sem_t sem, uint32_t timeout);

/**
 * Increments a semaphore's value.
 *
 * See https://pros.cs.purdue.edu/v5/tutorials/multitasking.html#semaphores for
 * details.
 *
 * \param sem
 *        Semaphore to post
 *
 * \return True if the value was incremented, false otherwise. If false is
 * returned, then errno is set with a hint about why the semaphore couldn't be
 * taken.
 */
bool sem_post(sem_t sem);

/**
 * Returns the current value of the semaphore.
 *
 * See https://pros.cs.purdue.edu/v5/extended/multitasking.html#extra for
 * details.
 *
 * \param sem
 *        A semaphore handle
 *
 * \return The current value of the semaphore (e.g. the number of resources
 * available)
 */
uint32_t sem_get_count(sem_t sem);

/**
 * Creates a queue.
 *
 * See https://pros.cs.purdue.edu/v5/extended/multitasking.html#queues for
 * details.
 *
 * \param length
 *        The maximum number of items that the queue can contain.
 * \param item_size
 *        The number of bytes each item in the queue will require.
 *
 * \return A handle to a newly created queue, or NULL if the queue cannot be
 * created.
 */
queue_t queue_create(uint32_t length, uint32_t item_size);

/**
 * Posts an item to the front of a queue. The item is queued by copy, not by
 * reference.
 *
 * See https://pros.cs.purdue.edu/v5/extended/multitasking.html#queues for
 * details.
 *
 * \param queue
 *        The queue handle
 * \param item
 *        A pointer to the item that will be placed on the queue.
 * \param timeout
 *        Time to wait for space to become available. A timeout of 0 can be used
 *        to attempt to post without blocking. TIMEOUT_MAX can be used to block
 *        indefinitely.
 *
 * \return True if the item was preprended, false otherwise.
 */
bool queue_prepend(queue_t queue, const void* item, uint32_t timeout);

/**
 * Posts an item to the end of a queue. The item is queued by copy, not by
 * reference.
 *
 * See https://pros.cs.purdue.edu/v5/extended/multitasking.html#queues for
 * details.
 *
 * \param queue
 *        The queue handle
 * \param item
 *        A pointer to the item that will be placed on the queue.
 * \param timeout
 *        Time to wait for space to become available. A timeout of 0 can be used
 *        to attempt to post without blocking. TIMEOUT_MAX can be used to block
 *        indefinitely.
 *
 * \return True if the item was preprended, false otherwise.
 */
bool queue_append(queue_t queue, const void* item, uint32_t timeout);

/**
 * Receive an item from a queue without removing the item from the queue.
 *
 * See https://pros.cs.purdue.edu/v5/extended/multitasking.html#queues for
 * details.
 *
 * \param queue
 *        The queue handle
 * \param buffer
 *        Pointer to a buffer to which the received item will be copied
 * \param timeout
 *        The maximum amount of time the task should block waiting for an item to receive should the queue be empty at
 *        the time of the call. TIMEOUT_MAX can be used to block indefinitely.
 *
 * \return True if an item was copied into the buffer, false otherwise.
 */
bool queue_peek(queue_t queue, void* const buffer, uint32_t timeout);

/**
 * Receive an item from the queue.
 *
 * See https://pros.cs.purdue.edu/v5/extended/multitasking.html#queues for
 * details.
 *
 * \param queue
 *        The queue handle
 * \param buffer
 *        Pointer to a buffer to which the received item will be copied
 * \param timeout
 *        The maximum amount of time the task should block
 *        waiting for an item to receive should the queue be empty at the time
 *        of the call. queue_recv() will return immediately if timeout
 *        is zero and the queue is empty.
 *
 * \return True if an item was copied into the buffer, false otherwise.
 */
bool queue_recv(queue_t queue, void* const buffer, uint32_t timeout);

/**
 * Return the number of messages stored in a queue.
 *
 * See https://pros.cs.purdue.edu/v5/extended/multitasking.html#queues for
 * details.
 *
 * \param queue
 *        The queue handle.
 *
 * \return The number of messages available in the queue.
 */
uint32_t queue_get_waiting(const queue_t queue);

/**
 * Return the number of spaces left in a queue.
 *
 * See https://pros.cs.purdue.edu/v5/extended/multitasking.html#queues for
 * details.
 *
 * \param queue
 *        The queue handle.
 *
 * \return The number of spaces available in the queue.
 */
uint32_t queue_get_available(const queue_t queue);

/**
 * Delete a queue.
 *
 * See https://pros.cs.purdue.edu/v5/extended/multitasking.html#queues for
 * details.
 *
 * \param queue
 *        Queue handle to delete
 */
void queue_delete(queue_t queue);

/**
 * Resets a queue to an empty state
 *
 * \param queue
 *        Queue handle to reset
 */
void queue_reset(queue_t queue);

/******************************************************************************/
/**                           Device Registration                            **/
/******************************************************************************/

/*
 * List of possible v5 devices
 *
 * This list contains all current V5 Devices, and mirrors V5_DeviceType from the
 * api.
 */
typedef enum v5_device_e {
	E_DEVICE_NONE = 0,
	E_DEVICE_MOTOR = 2,
	E_DEVICE_ROTATION = 4,
	E_DEVICE_IMU = 6,
	E_DEVICE_DISTANCE = 7,
	E_DEVICE_RADIO = 8,
	E_DEVICE_VISION = 11,
	E_DEVICE_ADI = 12,
	E_DEVICE_OPTICAL = 16,
	E_DEVICE_GPS = 20,
	E_DEVICE_SERIAL = 129,
	E_DEVICE_GENERIC __attribute__((deprecated("use E_DEVICE_SERIAL instead"))) = E_DEVICE_SERIAL,
	E_DEVICE_UNDEFINED = 255
} v5_device_e_t;

/*
 * Registers a device in the given zero-indexed port
 *
 * Registers a device of the given type in the given port into the registry, if
 * that type of device is detected to be plugged in to that port.
 *
 * This function uses the following values of errno when an error state is
 * reached:
 * ENXIO - The given value is not within the range of V5 ports (0-20), or a
 * a different device than specified is plugged in.
 * EADDRINUSE - The port is already registered to another device.
 *
 * \param port
 *        The port number to register the device
 * \param device
 *        The type of device to register
 *
 * \return 1 upon success, PROS_ERR upon failure
 */
int registry_bind_port(uint8_t port, v5_device_e_t device_type);

/*
 * Deregisters a devices from the given zero-indexed port
 *
 * Removes the device registed in the given port, if there is one.
 *
 * This function uses the following values of errno when an error state is
 * reached:
 * ENXIO - The given value is not within the range of V5 ports (0-20).
 *
 * \param port
 *        The port number to deregister
 *
 * \return 1 upon success, PROS_ERR upon failure
 */
int registry_unbind_port(uint8_t port);

/*
 * Returns the type of device registered to the zero-indexed port.
 *
 * This function uses the following values of errno when an error state is
 * reached:
 * ENXIO - The given value is not within the range of V5 ports (0-20).
 *
 * \param port
 *        The V5 port number from 0-20
 *
 * \return The type of device that is registered into the port (NOT what is
 * plugged in)
 */
v5_device_e_t registry_get_bound_type(uint8_t port);

/*
 * Returns the type of the device plugged into the zero-indexed port.
 *
 * This function uses the following values of errno when an error state is
 * reached:
 * ENXIO - The given value is not within the range of V5 ports (0-20).
 *
 * \param port
 *        The V5 port number from 0-20
 *
 * \return The type of device that is plugged into the port (NOT what is
 * registered)
 */
v5_device_e_t registry_get_plugged_type(uint8_t port);

/******************************************************************************/
/**                               Filesystem                                 **/
/******************************************************************************/
/**
 * Control settings of the serial driver.
 *
 * \param action
 * 			An action to perform on the serial driver. See the SERCTL_* macros for
 * 			details on the different actions.
 * \param extra_arg
 * 			An argument to pass in based on the action
 */
int32_t serctl(const uint32_t action, void* const extra_arg);

/**
 * Control settings of the microSD card driver.
 *
 * \param action
 * 			An action to perform on the microSD card driver. See the USDCTL_* macros
 *      for details on the different actions.
 * \param extra_arg
 * 		   	An argument to pass in based on the action
 */
// Not yet implemented
// int32_t usdctl(const uint32_t action, void* const extra_arg);

/**
 * Control settings of the way the file's driver treats the file
 *
 * \param file
 * 			A valid file descriptor number
 * \param action
 * 			An action to perform on the file's driver. See the *CTL_* macros for
 * 			details on the different actions. Note that the action passed in must
 *      match the correct driver (e.g. don't perform a SERCTL_* action on a
 *      microSD card file)
 * \param extra_arg
 * 		  	An argument to pass in based on the action
 */
int32_t fdctl(int file, const uint32_t action, void* const extra_arg);

/**
 * Action macro to pass into serctl or fdctl that activates the stream
 * identifier.
 *
 * When used with serctl, the extra argument must be the little endian
 * representation of the stream identifier (e.g. "sout" -> 0x74756f73)
 *
 * Visit https://pros.cs.purdue.edu/v5/tutorials/topical/filesystem.html#serial
 * to learn more.
 */
#define SERCTL_ACTIVATE 10

/**
 * Action macro to pass into serctl or fdctl that deactivates the stream
 * identifier.
 *
 * When used with serctl, the extra argument must be the little endian
 * representation of the stream identifier (e.g. "sout" -> 0x74756f73)
 *
 * Visit https://pros.cs.purdue.edu/v5/tutorials/topical/filesystem.html#serial
 * to learn more.
 */
#define SERCTL_DEACTIVATE 11

/**
 * Action macro to pass into fdctl that enables blocking writes for the file
 *
 * The extra argument is not used with this action, provide any value (e.g.
 * NULL) instead
 *
 * Visit https://pros.cs.purdue.edu/v5/tutorials/topical/filesystem.html#serial
 * to learn more.
 */
#define SERCTL_BLKWRITE 12

/**
 * Action macro to pass into fdctl that makes writes non-blocking for the file
 *
 * The extra argument is not used with this action, provide any value (e.g.
 * NULL) instead
 *
 * Visit https://pros.cs.purdue.edu/v5/tutorials/topical/filesystem.html#serial
 * to learn more.
 */
#define SERCTL_NOBLKWRITE 13

/**
 * Action macro to pass into serctl that enables advanced stream multiplexing
 * capabilities
 *
 * The extra argument is not used with this action, provide any value (e.g.
 * NULL) instead
 *
 * Visit https://pros.cs.purdue.edu/v5/tutorials/topical/filesystem.html#serial
 * to learn more.
 */
#define SERCTL_ENABLE_COBS 14

/**
 * Action macro to pass into serctl that disables advanced stream multiplexing
 * capabilities
 *
 * The extra argument is not used with this action, provide any value (e.g.
 * NULL) instead
 *
 * Visit https://pros.cs.purdue.edu/v5/tutorials/topical/filesystem.html#serial
 * to learn more.
 */
#define SERCTL_DISABLE_COBS 15

/**
 * Action macro to check if there is data available from the Generic Serial
 * Device
 *
 * The extra argument is not used with this action, provide any value (e.g.
 * NULL) instead
 */
#define DEVCTL_FIONREAD 16

/**
 * Action macro to check if there is space available in the Generic Serial
 * Device's output buffer
 *
 * The extra argument is not used with this action, provide any value (e.g.
 * NULL) instead
 */
#define DEVCTL_FIONWRITE 18

/**
 * Action macro to set the Generic Serial Device's baudrate.
 *
 * The extra argument is the baudrate.
 */
#define DEVCTL_SET_BAUDRATE 17

#ifdef __cplusplus
}
}
#endif

#endif  // _PROS_API_EXTENDED_H_