source: mainline/uspace/drv/bus/usb/ohci/hw_struct/transfer_descriptor.h

/*
 * Copyright (c) 2025 Jiri Svoboda
 * Copyright (c) 2011 Jan Vesely
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 * - Redistributions in binary form 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.
 * - The name of the author may not be used to endorse or promote products
 *   derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR 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.
 */

/** @addtogroup drvusbohci
 * @{
 */
/** @file
 * @brief OHCI driver
 */

#ifndef DRV_OHCI_HW_STRUCT_TRANSFER_DESCRIPTOR_H
#define DRV_OHCI_HW_STRUCT_TRANSFER_DESCRIPTOR_H

#include <assert.h>
#include <stdbool.h>
#include <stdint.h>

#include "mem_access.h"
#include "completion_codes.h"

/*
 * OHCI TDs can handle up to 8KB buffers, however, it can use max 2 pages.
 * Using 4KB buffers guarantees the page count condition.
 * (OHCI assumes 4KB pages)
 */
#define OHCI_TD_MAX_TRANSFER (4 * 1024)

/**
 * Transfer Descriptor representation.
 *
 * See OHCI spec chapter 4.3.1 General Transfer Descriptor on page 19
 * (pdf page 33) for details.
 */
typedef struct td {
        /** Status field. Do not touch on active TDs. */
        volatile uint32_t status;
#define TD_STATUS_ROUND_FLAG (1 << 18)
#define TD_STATUS_DP_MASK (0x3) /* Direction/PID */
#define TD_STATUS_DP_SHIFT (19)
#define TD_STATUS_DP_SETUP (0x0)
#define TD_STATUS_DP_OUT (0x1)
#define TD_STATUS_DP_IN (0x2)
#define TD_STATUS_DI_MASK (0x7) /* Delay interrupt, wait n frames before irq */
#define TD_STATUS_DI_SHIFT (21)
#define TD_STATUS_DI_NO_INTERRUPT (0x7)
#define TD_STATUS_T_FLAG (1 << 24) /* Explicit toggle bit value for this TD */
#define TD_STATUS_T_USE_TD_FLAG (1 << 25) /* 1 = use bit 24 as toggle bit */
#define TD_STATUS_EC_MASK (0x3) /* Error count */
#define TD_STATUS_EC_SHIFT (26)
#define TD_STATUS_CC_MASK (0xf) /* Condition code */
#define TD_STATUS_CC_SHIFT (28)

        /**
         * Current buffer pointer.
         * Phys address of the first byte to be transferred.
         */
        volatile uint32_t cbp;

        /** Pointer to the next TD in chain. 16-byte aligned. */
        volatile uint32_t next;
#define TD_NEXT_PTR_MASK (0xfffffff0)
#define TD_NEXT_PTR_SHIFT (0)

        /**
         * Buffer end.
         * Phys address of the last byte of the transfer.
         * @note this does not have to be on the same page as cbp.
         */
        volatile uint32_t be;
} __attribute__((packed, aligned(32))) td_t;

void td_init(td_t *, const td_t *, usb_direction_t, const void *, size_t, int);
void td_set_next(td_t *, const td_t *);

/**
 * Check TD for completion.
 * @param instance TD structure.
 * @return true if the TD was accessed and processed by hw, false otherwise.
 */
static inline bool td_is_finished(const td_t *instance)
{
        assert(instance);
        const int cc = (OHCI_MEM32_RD(instance->status) >> TD_STATUS_CC_SHIFT) &
            TD_STATUS_CC_MASK;
        /*
         * This value is changed on transfer completion,
         * either to CC_NOERROR or and error code.
         * See OHCI spec 4.3.1.3.5 p. 23 (pdf 37)
         */
        if (cc != CC_NOACCESS1 && cc != CC_NOACCESS2) {
                return true;
        }
        return false;
}

/**
 * Get error code that indicates transfer status.
 * @param instance TD structure.
 * @return Error code.
 */
static inline errno_t td_error(const td_t *instance)
{
        assert(instance);
        const int cc = (OHCI_MEM32_RD(instance->status) >>
            TD_STATUS_CC_SHIFT) & TD_STATUS_CC_MASK;
        return cc_to_rc(cc);
}

/**
 * Get remaining portion of buffer to be read/written
 * @param instance TD structure
 * @return size of remaining buffer.
 */
static inline size_t td_remain_size(td_t *instance)
{
        assert(instance);
        /* Current buffer pointer is cleared on successful transfer */
        if (instance->cbp == 0)
                return 0;
        /* Buffer end points to the last byte of transfer buffer, so add 1 */
        return OHCI_MEM32_RD(instance->be) - OHCI_MEM32_RD(instance->cbp) + 1;
}

#endif

/**
 * @}
 */